Errors

Every failure returns a unified error object. Always capture request_id for support and debugging.

Error shape

json

{
  "error": {
    "code": "bad_request",
    "type": "request_error",
    "message": "Human-readable message",
    "request_id": "...",
    "param": "model",
    "details": ["optional validation messages"]
  }
}

error.type: request_error | provider_error | server_error

Things to note

Validation failures are normally 400. 422 is used for no_compatible_model. Streaming errors may arrive inside the SSE stream after HTTP 200.

Fix the request

HTTP	Typical code	What to do
400	`bad_request`, `provider_invalid_request`, `capability_mismatch`	Fix body fields; check `param` / `details`
413	`payload_too_large`	Shrink body (limit 2 MB)
409	`idempotency_*`, `request_id_conflict`	Use a new Idempotency-Key or `x-request-id`

Authentication and access

HTTP	Typical code	What to do
401	`unauthorized`	Fix or recreate the API key
403	`forbidden`	Check project, org, or environment

Back off and retry

HTTP	Typical code	What to do
429	`rate_limit_exceeded`, `concurrency_limit_exceeded`, `spending_limit_exceeded`, `provider_rate_limit`	Back off; honor `Retry-After` and rate-limit headers when present
504	`gateway_timeout`, `provider_timeout`	Retry with a shorter prompt or later

Model capabilities

HTTP	Typical code	What to do
422	`no_compatible_model`	Change alias or drop unsupported capabilities (images, JSON mode, tools)

Availability

HTTP	Typical code	What to do
499	`request_cancelled`	Client aborted the request
502	`provider_protocol`	Upstream protocol issue — retry or contact support with request_id
503	`inference_not_enabled`, `providers_unavailable`, `limits_unavailable`	Service or upstream unavailable — retry later