Account
Errors
One envelope for every failure, with a stable code, a request id, and the HTTP status that goes with it.
The envelope
{ "error": { "code": "stale_frame", "message": "The preview frame is stale. Refresh it before acting.", "request_id": "req_…" } }The code is stable and meant for programs; the message is fixed text for people; request_id also arrives in the X-Request-Id header on every response. The SDKs raise StealthApiError with status, code, request_id, details and local (true when the JavaScript client's contracts refused the request before sending).
Statuses
| Status | When |
|---|---|
| 400 | The request does not match the contract (invalid_request, endpoint_not_allowed, tool_schema_invalid), or a webhook's signature does not verify (invalid_signature) |
| 401 | No valid session or key (unauthorized) |
| 402 | Billing gate: the owner account's credit is spent (insufficient_balance), or the project's monthly budget is reached (budget_exceeded) |
| 403 | The role does not permit it, or the resource is in another project (permission_denied, forbidden, email_not_verified, session_not_fresh), or a purge outside a zero-data-retention project (zero_data_retention_required) |
| 404 | Not found, or not visible to you (not_found) |
| 408, 413, 415 | Body too slow, too large, or the wrong content type |
| 409 | State conflicts: conflict, stale_frame, navigation_blocked, events_expired, model_unavailable, credential_unavailable, profile_busy, workspace_busy, workspace_quota, agent_limit, verdict_required, output_schema_violation, vision_unavailable, asset_not_ready, asset_limit, proxy_unavailable, integration_unavailable, tool_outcome_unknown, schedule_reference, team_changed, invitation_unavailable |
| 410 | An expired asset (asset_expired) |
| 429 | Capacity or rate: capacity_exceeded, concurrency_exceeded (the owner account's browsers are at its ceiling), rate_limited, upload_busy, registry_full |
| 500 | internal_error, storage_error |
| 502 | Execution failed: browser_launch_failed, navigation_failed, snapshot_failed, action_failed, agent_failed, output_truncated (the model's output was cut by its output-token cap mid tool call; the run ends once, with that cause), agent_incomplete, extract_failed, worker_failed, cleanup_failed, network_test_failed, model_test_failed, integration_failed, profile_state_failed, asset_failed |
| 503 | provider_unavailable (a feature the deployment has not configured, such as email), shutting_down |
| 504 | operation_timeout |
Codes on resources
Some codes describe how a run ended rather than a request that failed; they appear in the run's error with a 200 read:
| Code | Meaning |
|---|---|
task_failed | The agent reported it could not complete the task; its account is in output |
agent_limit | The action or failure budget brought the verdict turn and the agent did not call done |
agent_incomplete | The agent stopped in prose without a verdict |
spend_limit | The run reached its max_spend_usd |
cleanup_failed | On a browser: release could not be verified; capacity stays reserved |
Handling advice
stale_frame: observe again and retry the action with the newframe_id. The SDKs do this once for you.conflicton a browser action: an Agent run owns the browser — wait, or cancel the run.capacity_exceeded: the request waited its turn for a browser slot and none freed in time (or the line was full); stop an instance you own or retry later.concurrency_exceeded: the owner account's projects already run as many browsers as its ceiling allows; stop one, or raise the ceiling with paid credit (it follows lifetime top-ups and never goes down). Running work is never refused.insufficient_balance/budget_exceeded: new work only; running work finishes. The project's owner adds credit on the Billing page, or raises the project's monthly budget.conflicton a write with arevision: read the resource, then write with the current revision.- 5xx and
operation_timeout: the operation may or may not have taken effect; read the resource before repeating anything with external effects.