Errors

Every error response uses a single JSON envelope with a stable, machine-readable code. Branch on the code field, not on the human-readable message, which may change.

Error envelope

All error responses share this shape:

{
  "error": {
    "code": "invalid_request",
    "message": "ttlMs must be a positive integer",
    "details": { "field": "ttlMs" }
  }
}

• code — lowercase snake_case identifier, stable across releases.
• message — human-readable explanation, for logs and debugging.
• details — optional object with extra context, varies by code.

Error codes

These are the error codes you can encounter across the public API:

File operations have additional codes such as path_outside_workspace, file_not_found, and directory_not_empty. See Files for the full list.

[!NOTE] A non-zero command exit code is not an API error. The HTTP request succeeds, and you read the outcome from the Command object's status and exitCode fields.

Handling 4xx errors

A 4xx response means the request itself is the problem. Don't retry the same request unchanged — fix it first:

• invalid_request, sandbox_ttl_exceeded, reserved_env_key — correct the request body or parameters.
• unauthenticated, invalid_api_key, forbidden — fix the credential or its scopes. See Authentication.
• not_found, sandbox_destroyed — the resource is gone or invisible to your key; don't retry.
• quota_exceeded and rate_limited are the exception: both return 429 and are retryable. For rate_limited, retry after a short backoff. For quota_exceeded, free up capacity (for example, kill idle sandboxes) or upgrade your plan.

Handling 5xx errors

A 5xx response means something failed on the server side. These are generally safe to retry with exponential backoff. For POST endpoints that create or run resources, retry with the same Idempotency-Key so a retry can never duplicate work. See Pagination and idempotency.

command_timed_out is the exception: the command genuinely ran out of time, so retrying the identical request usually times out again. Raise timeoutMs or reduce the work.

Next steps

• Make retries safe in Pagination and idempotency.
• Review file-specific codes in Files.