code. Switch on code, not on the message.
{ "error": { "code": "sandbox-closed", "message": "sandbox sbx_… is closed (idle)", "fix": "create a new sandbox", "requestId": "req_…" } }
fix, when present, says what to do. A 5xx from a proxy in front of the plane can carry a body that is not JSON.
Codes for API callers
| Status | Code | Meaning, and what to do |
|---|---|---|
| 400 | not-an-object | The body must be a JSON object |
| 400 | unknown-field | The body has a field this route does not take. The fix lists the fields it does |
| 400 | missing-repo, bad-repo, bad-kind, missing-command, missing-agent, no-command-on-agent, no-agent-on-command, bad-artifacts, bad-session, bad-timeout, bad-record | A task or sandbox field is wrong. The message names the field. bad-repo: not an https URL, carries credentials, or over 2048 characters |
| 400 | bad-artifact-name | A task promised an artifact name that breaks the artifact name rules |
| 400 | missing-cmd, bad-cmd, bad-envs | A command’s cmd is empty or over 64 KiB, or envs is not an object of string values (at most 64, with names like NAME_1) |
| 400 | bad-path | A file path or cwd is absolute, contains .., or uses characters other than letters, digits, ., _, - and / |
| 400 | bad-max-dimension | maxDimension must be an integer from 64 to 8192 |
| 400 | bad-input | An input call’s screen or one of its actions is wrong, or the call asks for more than its limits. The message names the action and field. Nothing was performed |
| 400 | bad-after | A recording’s live stream took an after that is not a whole number |
| 400 | bad-goal, bad-max-steps, bad-max-duration-ms, bad-model, missing-model-key | An agent run’s field is wrong, or the x-anthropic-api-key header is missing (see Hand the screen a goal) |
| 400 | bad-state, bad-limit, bad-cursor | A list query is wrong. bad-cursor: the cursor names no item of yours; start the listing again without one |
| 400 | bad-wait | wait on GET /v1/tasks/:id, GET /v1/sandboxes/:id/commands/:commandId or GET /v1/runs/:id must be a number of seconds from 0 to 60 |
| 400 | bad-days | days must be an integer from 1 to 90 |
| 400 | bad-idempotency-key | Idempotency-Key must be 1 to 255 characters |
| 401 | unauthorized | The credential is missing or wrong. See Authentication |
| 402 | payment-method-required | The available credit, after the work already in flight, cannot cover this work’s worst case. Ask for a shorter timeoutMs. Buy credit or enable auto-reload in the console under Billing; saving a card alone is insufficient |
| 402 | credit-ceiling | A team billed monthly would owe more than its credit ceiling with this work’s worst case added. Ask for a shorter timeoutMs, wait for work in flight to end, or ask offstage to raise the ceiling |
| 402 | budget-exceeded | This month’s spend beyond the credit, plus the work in flight and this request the credit does not cover, could pass the enforced monthly budget (credit never counts against it). Raise or lift the spending limit in the console under Billing, or ask for a shorter timeoutMs |
| 402 | payment-failed | An invoice’s charge failed, and new work is paused. Update the card in the console under Billing, and the invoice is charged again at once |
| 403 | console-only | Only a signed-in console session may do this (keys, budget, card, members) |
| 403 | operator-only, box-only | The route is not part of the customer API |
| 403 | forbidden | The signed-in user’s role does not allow it (owner-only), or a cross-site cookie request |
| 404 | not-found | No such sandbox, command, task, artifact or key, or it belongs to another team. A finished command’s answer is kept for at most 10 minutes (see Run a command), an ended task for 30 days, and an artifact for 7 days after its task ends |
| 404 | recording-not-found | No recording with that id for this team: a headless sandbox or task, one made with "record": false, or one past its 7 days (see Recordings) |
| 404 | no-such-route | No such method and path |
| 404 | file-not-found | A sandbox file read named something that is not a file |
| 408 | body-timeout | The request body did not all arrive in time: 30 s for a JSON body, 10 s on /v1/auth/*, 40 min for a file write (which arrives only as fast as the Mac takes it). Send it again |
| 409 | sandbox-not-ready | The sandbox is still waiting for a free Mac slot after 30 s. Retry shortly, or poll GET /v1/sandboxes/:id until it is ready |
| 409 | sandbox-closed | The sandbox has closed. The message gives the reason. Create a new one |
| 409 | headless-sandbox | A screenshot of, input to, or an agent run on, a headless sandbox. These require "session": "gui" |
| 409 | display-changed | An input call’s screen is not the shape of the sandbox’s display. Take a new screenshot and read the coordinates from it |
| 409 | no-target | An input call found no app in front to deliver to. Open or click one first |
| 409 | agent-running | Another agent run is driving this sandbox’s screen. Wait for it (GET /v1/runs/:id?wait=50), or use another sandbox |
| 409 | op-failed | The Mac reported an error running the op. The message starts with the Mac’s own code. sandbox-busy means the sandbox already had 16 ops running and no room for another to wait (see Concurrency inside a sandbox): retry once some end |
| 409 | gui-paused | GUI work (a gui sandbox, a gui task, or a GitHub Actions job on offstage-macos-gui) has been temporarily paused by the operator. Headless work runs as usual. Use "session": "headless" if the work needs no screen; retrying GUI creates does not bypass the pause |
| 409 | no-capacity | Macs are online, but no slot in the fleet takes this session right now (usually gui: every GUI slot is busy, or being made ready again after its last customer). GET /v1/capacity shows what is ready. Use "session": "headless" if the work needs no screen, or retry later |
| 409 | already-ended | A cancel of a task that had already ended. The answer’s message gives its final state |
| 409 | bad-artifact-name | An artifact download named a file that could not be an artifact (see the 400 above) |
| 409 | idempotency-key-reused | The same Idempotency-Key was sent with a different body. Use a new key for a new request |
| 409 | idempotency-key-in-use | The first request with this key is still being handled. Retry in a moment to get its answer |
| 409 | idempotency-key-spent | This key made a task that is no longer kept. Use a new key to make another |
| 413 | file-too-large | A file write or a file read over 2 GiB |
| 413 | body-too-large | A JSON body over 1 MiB (a command is 64 KiB at most; the rest is spare), or a /v1/auth/* body over 16 KiB. A body is counted as it arrives, refused the moment it passes its cap, and the connection is closed |
| 403 | email-unverified | The team’s owner has not verified their email yet, so the team cannot create sandboxes, tasks or API keys, or add members. Making a key also needs your own email verified. Open the link emailed at signup, or send a new one from the console |
| 429 | rate-limit | This team has sent more than 120 requests in the last 60 s, whatever key it used, or this client address more than 600 (fewer on sign-up, sign-in and verify). The Retry-After header gives the seconds left; a ?wait= long-poll is one request, not a poll loop |
| 429 | task-backlog | The team already has 16 tasks queued, the most it may queue at once. Submit more as these start, or cancel one |
| 429 | queue-full | The plane already has 500 tasks queued across every team. Retry after the Retry-After seconds (60) |
| 429 | uploads-busy | A file write past what the service takes in at once: 24 MiB of file writes held for one team (a write holds at most 8 MiB however large it is, so three large ones fit), or the share every team’s writes have together. The message says which. Send it again once your other writes finish; Retry-After is 1 s |
| 500 | internal | A bug in the plane. Quote the requestId |
| 504 | op-timeout | The Mac did not answer the op within its deadline (a command’s timeoutMs plus 30 s, or 90 s for a file read, each 4 MiB part of a file write, or a screenshot), counted from when it started the op. Or no place freed in the sandbox for the op within that deadline, and it never ran. GET the sandbox: if it closed as box-lost, start over, otherwise retry |
Codes from console calls
| Status | Code |
|---|---|
| 400 | bad-email, weak-password (at least 10 characters), bad-name, missing-password, missing-name, missing-team, bad-team, bad-budget, bad-return-url, missing-session, bad-token (a verification or password-reset link that was used, expired or copied wrong), bad-kind (a key’s kind is not personal or service) |
| 401 | bad-credentials, no-team |
| 403 | not-a-member, team-changed (renaming the team, adding a member and making a key check the caller again once the body is in: you were removed or left meanwhile, or the session switched to another team. Nothing was changed) |
| 409 | email-taken, already-member, last-owner, checkout-incomplete, no-card, no-customer, no-portal, already-verified |
| 429 | too-many-attempts (10 failed sign-ins at one email from one address in 15 minutes pause that address at that email only. Once an email has 50 failed sign-ins from all addresses in its 15-minute window, an address that has failed there is paused until 15 minutes after its own first miss, and an address with no misses there still gets its try. A password reset or a GitHub or Google sign-in clears them. Retry-After gives the seconds left), rate-limit (per address: 5 sign-ups an hour, 20 sign-ins or verifications a minute; 3 verification emails an hour per person), signups-full (the plane’s signups for the day are taken) |
| 502 | mail-failed (the verification email could not be sent; try again) |