Errors

Every failed API call answers with one JSON shape, and the CLI and MCP server pass it on unchanged:

1{"error": {"code": "not_found", "message": "no such sandbox", "remedy": "fix_input"}}

Branch on code, never on message. remedy says what to do:

`remedy`	Meaning
`fix_input`	The same request fails the same way. Change it.
`retry`	Transient. Retry with backoff.
`raise_limits`	It needs more room or more time (a bigger timeout, memory or disk).
`contact_support`	Nothing the caller can do. Report it with the sandbox id.

Codes

`code`	HTTP	`remedy`	Meaning
`invalid_argument`	400	`fix_input`	Malformed request. Unknown JSON fields are refused too.
`unauthenticated`	401	`fix_input`	No key, or the key is invalid, revoked or expired.
`forbidden`	403	`fix_input`	A valid key without the scope the route needs.
`account_suspended`	403	`contact_support`	The account is suspended.
`permission_denied`	403	`fix_input`	The sandbox user may not do this (a file, a path).
`not_found`	404	`fix_input`	No such sandbox, process, path, build, template or key. Another account's sandbox is also `not_found`.
`sandbox_not_ready`	409	`retry`	The sandbox is still `allocating`. Retry once it is `running`.
`template_not_ready`	409	`retry`	The template has no version under that tag yet; a build of it is still running.
`cancelled`	409	`fix_input`	The work was cancelled (a build, for instance).
`lease_expired`	410	`fix_input`	The sandbox's lease ran out and it was reclaimed. See leases.
`out_of_memory`	422	`raise_limits`	The OOM killer took the command or the sandbox. Give it more `memory_mib`.
`out_of_disk`	422	`raise_limits`	The filesystem is full. Free space or ask for more `disk_mib`.
`capacity_exhausted`	503, or 429	`retry`	No room for another sandbox. 429 means the account is at its slot limit; 503 means the host is full.
`unavailable`	503	`retry`	Something runner runs did not answer. The CLI and MCP also use it when they cannot reach the API.
`timeout`	504	`raise_limits`	A command ran past its `timeout_ms`.
`unsupported`	501	`fix_input`	The runtime or this deployment does not implement it (for example previews not enabled). Do not retry.
`internal`	500	`contact_support`	A bug in runner. Retry once, then report it.

The CLI adds nothing new: a usage mistake is invalid_argument, an interrupted run is cancelled, and a wait that ran out is timeout.

Where codes appear besides the HTTP status

A sandbox that ended for a reason has it in error_code (out_of_memory, lease_expired, ...), and in its terminated event.
A streamed exec or build log ends with an error event holding the same object under "error".
A non-streamed exec that timed out or was OOM-killed answers 504 / 422 with both "error" and the command's partial "result".

Ask AI about this page