Errors

Every error response is JSON with a stable code field. We never leak stack traces. If the response doesn’t match this table, please report it.

{
  "error": {
    "code": "ssrf_blocked",
    "message": "target_url host resolves to a private IP range"
  }
}

Auth

Status	Code	Meaning
`401`	`missing_auth`	No `Authorization` header.
`401`	`invalid_api_key`	Key not recognised, revoked, or malformed.
`402`	`payment_required`	Customer plan is `suspended`.
`403`	`forbidden`	Resource exists but isn’t yours.

Status	Code	Meaning
`400`	`invalid_request`	Body failed schema validation.
`400`	`ssrf_blocked`	`target_url` is private / non-https / `.local`.
`400`	`credential_mismatch`	`target_host` ≠ `target_url` host.
`400`	`model_unavailable`	Requested `model` is not configured.
`404`	`not_found`	Resource ID doesn’t exist (or isn’t yours).

Status	Code	Meaning
`429`	`rate_limited`	Per-key request throttle. Use `Retry-After`.
`429`	`concurrent_sessions`	You’re at your concurrent-session limit (default 5).
`409`	`run_in_terminal_state`	Cancelling a run that has already finished.

Status	Code	Meaning
`500`	`internal`	Unexpected. We’ve logged it; please reference `X-Request-Id`.
`502`	`container_unavailable`	Browser layer couldn’t start. We retry on your behalf.
`503`	`service_unavailable`	Upstream LLM or Container provider degraded.

Retry on 429, 502, 503 with exponential backoff. Do not retry on 4xx validation errors — fix the request.