Errors

Most errors follow the OpenAI shape, with a nested error object:

{
  "error": {
    "message": "Model is currently at capacity. Please retry shortly.",
    "type": "server_error",
    "code": "model_overloaded"
  }
}

Status codes

Status	`code`	Meaning	Retry?
`400`	—	Malformed request, or an unsupported `reasoning_effort` for this model.	No — fix the request
`401`	—	Missing, malformed, revoked or expired API key, or a source IP outside the key’s allowlist.	No
`403`	—	Key is valid but not permitted for this workspace or resource.	No
`404`	—	Unknown model slug, or a model not available to you.	No
`422`	`INSUFFICIENT_BALANCE`	Workspace wallet is exhausted.	No — top up
`429`	`rate_limit_exceeded`	Workspace request-rate limit exceeded.	Yes
`503`	`model_overloaded`	Queued, but the model’s maximum wait elapsed.	Yes
`503`	`queue_full`	The model’s queue is at its depth limit.	Yes
`503`	`model_not_configured`	Model has no admission configuration.	No — contact us
`500`	—	Unexpected server or upstream transport failure.	Yes, with backoff

Errors returned by the upstream model itself in the 4xx range are passed through as-is, so a malformed tools payload surfaces the model’s own message.

Insufficient balance (422)

{
  "success": false,
  "error": "Insufficient balance. Your current balance is $0.00. Please top up your account to continue using the API.",
  "code": "INSUFFICIENT_BALANCE"
}

This is checked before the model runs, so a request rejected this way costs nothing. Top up from Billing to resume.

Rate limited (429)

{
  "error": {
    "message": "Rate limit exceeded. Please slow down your requests.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

The response carries Retry-After in seconds. See Rate limits and queueing for the headers on every response and how to pace requests.

Capacity (503)

model_overloaded and queue_full both mean the model is busy rather than broken, and both are safe to retry — Retry-After is 5 and 10 seconds respectively. These are the two you should expect to see under load, and the queueing guide explains why.

Retry guidance

Always honour Retry-After when present. It is a real signal, not a formality.
Retry 429, 503 and 500. Do not retry other 4xx — they will fail identically.
Use exponential backoff with jitter for 500, so a transient upstream problem doesn’t turn into a synchronised retry storm.
Cap total attempts. A queued request may already have waited a long time before failing, so unbounded retries can multiply latency rather than fix it.