# Limits

URL: https://heaven.dev/docs/limits
Updated: 2026-11-21

Heaven limits pool resource use and the rate of management requests. Errors identify the resource or request limit reached.

## Pool capacity

A pool's **Metrics** tab shows usage against its allocation. Read the same information from the CLI:

```sh
heaven pool view web
heaven pool usage web --range 24h
```

If a Computer is waiting for memory, reduce the running workload or [resize the pool](https://heaven.dev/docs/pools#sizing-a-pool). An `over_capacity` error identifies the resource needed by a refused request.

## Storage

Disks and snapshots share the pool's storage allowance. Data retained by a snapshot remains allocated after the original file is deleted.

Each Computer you add to a [pool](https://heaven.dev/docs/pools#using-a-pool) counts as at least 1 GB of its storage, however little it stores. A create, copy, restore or move that would take the pool past its storage boundary is refused with `over_capacity`.

Disk writes stop at 120% of the allowance. New snapshots are refused above that boundary. Free files and unused snapshots, or increase the pool's storage, to resume writes.

A pool cannot be reduced below the space its data requires. Read [snapshot sizes](https://heaven.dev/docs/reference/snapshots/view) and pool usage before resizing.

## Request rates

Management commands share a per-user rate limit across interfaces and keys.

| Requests | Sustained rate | Burst allowance |
| --- | ---: | ---: |
| All management commands | 20 per second | 300 |
| State-changing commands | 1 per second for each unit, up to 16 | 60 seconds of the rate |

The rate for state-changing commands follows the capacity of the largest account you belong to. It counts the units that account has bought and holds now, whether or not its pools use them. A user whose accounts have bought nothing gets the rate of one unit.

| Units | State-changing commands per second | Burst allowance |
| --- | ---: | ---: |
| 1 or none | 1 | 60 |
| 2 | 2 | 120 |
| 4 | 4 | 240 |
| 8 | 8 | 480 |
| 16 or more | 16 | 960 |

Capacity you buy raises the rate within a minute. Each state-changing command also counts toward the 20 per second for all commands and their burst of 300. Heaven refuses a command beyond either limit with `rate_limited`, and nothing waits in a queue.

A create request in an existing pool uses the general rate, counting as one management command even if it creates several Computers. The pool can have up to 10 creates or copies in progress per [unit of capacity](https://heaven.dev/docs/pools#sizing-a-pool), with a ceiling of 160. Each Computer counts from acceptance until its operation ends. The ceiling is a judgment call to keep one pool's batch from holding up work in other pools.

A batch above the pool's limit returns `over_capacity`. If other creates temporarily leave too few places, the request returns `busy`. If Computers waiting for pool memory leave too few places, the request returns `over_capacity`. Accepted Computers may wait their turn to boot.

Guest execution and feedback use only the general rate.

A [`rate_limited` response](https://heaven.dev/docs/reference/errors#rate_limited) returns HTTP 429 and a delay in `Retry-After` and `retry_after`. Wait for that delay before retrying.
