Docs · Operate & reference

Handle failed requests

Branch on the HTTP status first. For direct API calls, read the structured error body for a human-readable message and optional machine-readable code.

Start with the status

Status	Meaning	When
`400`	Bad request	Malformed JSON, missing messages, or an unknown model id.
`401`	Unauthorized	Missing, malformed, or revoked API key. Rotate or re-check the key.
`429`	Rate limited	Per-org RPM exceeded, or the org budget cap is reached. Honor Retry-After.
`502`	Bad gateway	The upstream node returned an error or was unreachable during routing.
`503`	Service unavailable	The gateway is not currently configured or reachable.

Inspect the response body

Direct calls return an OpenAI-compatible error object. Displayerror.message to an operator; branch primarily on the HTTP status.

{
  "error": {
    "message": "human-readable description",
    "type": "invalid_request_error",
    "code": null
  }
}

Requests made through the in-app console proxy are flattened to a { "error": "message" } string for display. Direct calls to the branded API return the full object shown above.

Retry transient failures

Do not retry 400 or 401 without correcting the request or credentials. For 429, respect Retry-After and back off. Treat 502 and 503 as transient and use bounded backoff rather than an immediate retry loop.