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, 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).

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.

TypeScriptimport { 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);

Pythonfrom withruntime import Runtimewith 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.

TypeScriptimport { 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);  }}

Pythonfrom withruntime import Runtime, RuntimeErrorruntime = 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).

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).
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).
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).
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).
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). For bursts, see agent evals and SWE-bench and RL environments.

Facts on this page were checked on 25 September 2026.