Errors

Envelope

Every error — Cloud API or CLI JSON mode — carries a machine-readable envelope with a request_id. Include it in support requests:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "type": "unauthorized",
    "message": "Invalid API key"
  }
}

Session and billing errors add code and retryable:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "type": "payment_required",
    "code": "spending_limit_exceeded",
    "message": "Spending limit exceeded",
    "retryable": false
  }
}

Status codes

Status	Meaning	What to do
`400`	Bad action/args (e.g. `computer.*` on a browser-only session)	Fix the request — don't retry as-is
`401`	Missing/invalid API key, or wrong `x-session-secret`	Rotate the key; re-read the secret saved at create time
`402`	Spending limit exceeded or billing `past_due`	Raise the cap / settle billing — see Usage & Billing
`429`	Abuse guard tripped	Back off and retry — see Rate limits
`5xx`	Platform error	Retry with exponential backoff

Retry rules

Retry: 429 and 5xx — exponential backoff with jitter, then give up after ~3 attempts.
Don't retry: 400, 401, 402 (retryable: false) — the request or account needs fixing first.
Sessions: a failed session status is terminal — destroy it and create a new one rather than polling forever.
Answers: status: insufficient_information is not an error — the evidence was thin. Narrow the query or add sources instead of retrying verbatim.

Debugging checklist

Copy the request_id from the failing response.
Re-run with full output: GET /v0/usage for account state, GET /v0/sessions/{id} for session state.
Check Rate limits (abuse guards, TTLs) and Usage & Billing (spending caps).
Look for the request in the dashboard, then file an issue with the request_id.

Interactive reference

Try every endpoint in your browser at api.omniscout.xyz/docs — JSON at api.omniscout.xyz/api/openapi.