# How to handle no_capacity and quota_exceeded errors

Let the SDK wait: a create refused with `no_capacity`, `quota_exceeded` or `trial_busy` sends the same request again for up to two minutes.

**On Runtime a burst of creates past a limit queues instead of failing, and a
refusal costs nothing.** A paid account starts with room for 100 sandboxes at
once, 200 vCPUs and 400 GiB of memory across the running ones, and support
raises that on request; the free trial runs eight at once
([how many at once](/docs/pricing#how-many-at-once), checked 25 September 2026).
A paused sandbox holds no CPU or memory, so pausing idle work makes room.

## What each refusal means

| Code                     | Status | Cause                                                     | Clears when                                     |
| ------------------------ | ------ | --------------------------------------------------------- | ----------------------------------------------- |
| `no_capacity`            | 409    | No host in the region has room right now                  | A host frees room                               |
| `busy`                   | 503    | A host is briefly busy                                    | On its own; the SDKs retry it                   |
| `trial_busy`             | 409    | Eight trial sandboxes are running; `details` names them   | One of them stops or pauses                     |
| `quota_exceeded`         | —      | The account is at its sandbox, vCPU, memory or disk limit | Something stops or pauses, or support raises it |
| `trial_exhausted`        | 402    | The 50 trial hours are used                               | Never: use paid credit                          |
| `spending_limit_reached` | 402    | The key's daily limit would be passed                     | Older spending leaves the 24-hour window        |

The first four are temporary. The last two are not, and the SDKs do not wait on
them ([API errors](/docs/api#responses-and-errors)).

## Set how long a create waits

The wait is added to the call's timeout, not taken from it. Set it on the
client for every create, or on one create; `0` fails at once.

```ts
import { Runtime } from "withruntime";

// A nightly batch that may queue for ten minutes behind other jobs.
const runtime = new Runtime({ waitForCapacityMs: 600_000 });
await using sbx = await runtime.sandboxes.create();

// An interactive request that should fail fast and tell the user.
await using now = await runtime.sandboxes.create({}, { waitForCapacityMs: 0 });
console.log(sbx.id, now.id);
```

```python
from withruntime import Runtime

with Runtime(wait_for_capacity=600) as runtime:
    with runtime.sandboxes.create() as sbx:
        with runtime.sandboxes.create(wait_for_capacity=0) as now:
            print(sbx.id, now.id)
```

## When the wait runs out

The refusal is then thrown as it came. Its `retryable` is `true` for
`no_capacity` and `trial_busy`, so a loop of your own can keep going. Keep the
same idempotency key across the loop, so a create that did land is answered
again rather than made twice.

```ts check
import { Runtime, RuntimeError } from "withruntime";

const runtime = new Runtime({ waitForCapacityMs: 120_000 });
const options = { idempotencyKey: "nightly-2026-09-25-shard-7" };
for (let attempt = 1; ; attempt++) {
  try {
    await using sbx = await runtime.sandboxes.create({ labels: { shard: "7" } }, options);
    console.log((await sbx.exec("nproc")).stdout);
    break;
  } catch (error) {
    if (!(error instanceof RuntimeError) || !error.retryable || attempt === 5) throw error;
    console.warn(error.code, error.hint, error.requestId);
  }
}
```

```python check
from withruntime import Runtime, RuntimeError

runtime = Runtime(wait_for_capacity=120)
for attempt in range(1, 6):
    try:
        with runtime.sandboxes.create(idempotency_key="nightly-2026-09-25-shard-7",
                                      labels={"shard": "7"}) as sbx:
            print(sbx.exec("nproc").stdout)
        break
    except RuntimeError as error:
        if not error.retryable or attempt == 5:
            raise
        print(error.code, error.hint, error.request_id)
```

From a terminal, `runtime sandbox ls` shows what is holding the room, and
`runtime sandbox pause <id>` gives a running sandbox's CPU and memory back
while keeping its state ([pause and resume](/how-to/pause-and-resume-a-sandbox)).

## Mistakes that make it worse

- **A new sandbox per retry.** A retry with a new key can land twice. Reuse the
  key, as above ([idempotency keys](/how-to/retry-safely-with-idempotency-keys)).
- **Asking a trial fork for more than eight copies.** It never fits, however
  long you wait. Ask for fewer, or fork onto paid credit
  ([forking](/how-to/fork-a-running-sandbox)).
- **Replacing a sandbox that will not wake.** A wake needs room on the sandbox's
  own host, and a full host can refuse it while keeping the saved state. Retry
  the wake later; do not delete the sandbox as a retry step
  ([a paused sandbox will not wake](/docs/troubleshooting#a-paused-sandbox-will-not-wake)).
- **Looping on a spending limit.** `spending_limit_reached` counts the last 24
  hours, and only a person can raise it on the keys page
  ([daily spending limits](/how-to/set-a-daily-spending-limit)).
- **Retrying `fork_unavailable` or `previews_unavailable`.** These 503s mean the
  feature is switched off there on purpose; retrying will not help.

## Ask for more room

The starting limits are not a price tier. Write to support with the numbers you
need: `runtime support "we need 400 sandboxes at once for evals"`
([feedback and support](/docs/feedback-and-support)). For bursts, see
[agent evals and SWE-bench](/use-cases/agent-evals-and-swe-bench) and
[RL environments](/use-cases/rl-environments).

Facts on this page were checked on 25 September 2026.