Every Caffeine app runs on the Internet Computer — a decentralised cloud network where computation costs cycles, a unit of fuel that powers your app. Your app's canisters need cycles to process requests, store data, and make external API calls.
You do not normally need to think about cycles. Caffeine manages them automatically. In rare cases, a canister can temporarily run low on cycles and become unavailable. This article explains what cycles are, why they can run out, and what happens when they do.
How Caffeine manages cycles
When you publish your app, Caffeine creates permanent canisters and configures automatic cycle monitoring. A monitoring system periodically checks each canister's cycle balance and tops it up if it has dropped below a safe threshold. Cycle top-ups are charged as a small hosting cost against your credit balance.
For the vast majority of apps, this automatic management keeps everything running without any intervention.
What consumes cycles
Every operation a canister performs costs cycles. The main consumers are:
- Frontend asset storage — canisters that store large amounts of frontend assets (JavaScript bundles, images, fonts) consume cycles proportional to the data stored. This is the most common reason a canister's cycle balance drops faster than expected.
- External HTTP calls — each call to an external API costs a fixed amount of cycles. Apps that poll external services frequently (for example, every 10 seconds) can deplete their cycle balance quickly.
- Data storage — storing data in your canister's stable memory costs cycles proportional to the amount stored.
- Computation — processing requests, running backend logic, and handling user interactions all consume cycles, though at much lower rates than storage and HTTP calls.
What happens when cycles run out
In rare cases, a canister's cycles can be consumed faster than the monitoring system tops them up. When a canister's cycle balance reaches zero, the Internet Computer pauses it. You may see an error like IC0508, "Service temporarily unavailable", or your app may simply stop responding.
This affects a very small fraction of projects on Caffeine — primarily those with large frontend assets or high HTTP call frequency.
When this happens, the canister is not deleted and your data is safe. The monitoring system will detect the low balance and top the canister back up automatically. Your app should be back online within approximately 20 minutes without any action on your part.
Preventing cycle issues
If your app has experienced a temporary outage due to cycles, there are steps you can take to reduce cycle consumption:
- Reduce HTTP polling frequency. If your app checks an external API every 10 seconds, change it to every 60 seconds or longer. Most use cases do not need sub-minute polling.
- Cache responses. If the external data does not change frequently, store the last response and only make a new call when needed.
- Keep frontend assets lean. Large numbers of high-resolution images or large JavaScript bundles stored as frontend assets increase storage costs. Where possible, use Caffeine's file storage for user-uploaded content rather than bundling everything as a frontend asset.
How cycle management may evolve
Caffeine is exploring ways to improve how cycles are managed, including faster monitoring intervals and better handling of canisters with large storage footprints. The goal is to eliminate temporary outages entirely. Nothing here is confirmed — these are directions being evaluated, not features on a fixed roadmap.
Frequently asked questions
Will I lose data if my canister pauses?
No. A paused canister retains all its data. Once cycles are restored by the monitoring system, everything comes back exactly as it was.
Do I need to do anything if my app goes down due to cycles?
In most cases, no. The monitoring system will detect the issue and top up your canister automatically. If your app does not recover within 30 minutes, contact support with your project name.
Do automatic cycle top-ups cost credits?
Yes. When the monitoring system tops up your canister, a small hosting cost is deducted from your credit balance. Under normal usage this cost is negligible. Apps with large frontend assets or frequent HTTP outcalls consume more cycles and therefore incur higher top-up costs.
Why did my canister run out of cycles even though monitoring is automatic?
The monitoring system checks balances periodically. If a canister consumes cycles faster than the monitoring interval — typically due to large stored assets or very frequent HTTP calls — it can briefly run out before the next top-up. Caffeine is actively working to reduce these gaps.
The error says IC0508 — what does that mean?
IC0508 is the Internet Computer's error code for a paused canister. It means the canister ran out of cycles and the network stopped it to prevent further unpaid computation. The monitoring system will restore cycles automatically.