> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Errors

> One error shape with a stable code, and what to do about each code.

Every failure has the same envelope and a stable `code`. Switch on `code`, not on the message.

```json theme={null}
{ "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](https://offstage.cloud/docs/api/tasks.md#artifacts) |
| 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](https://offstage.cloud/docs/api/sandboxes.md#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](https://offstage.cloud/docs/api/authentication.md) |
| 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](https://offstage.cloud/docs/api/sandboxes.md#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](https://offstage.cloud/docs/api/recordings.md)) |
| 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](https://offstage.cloud/docs/api/sandboxes.md#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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.