Reference / Errors

Errors

Standardized across every provider, with a request ID on every failure and explicit retry semantics.

Error shape

{
  "error": {
    "type": "rate_limit",
    "message": "key requests limit of 600 per minute exceeded; retry in 2s",
    "code": "rate_limit",
    "param": "requests",
    "request_id": "req_01J9F3KJ2MQ8ZV5T7XB0N4A6WD",
    "retriable": true
  }
}
// plus X-Request-Id on every response; on a 429 also Retry-After
// and X-RateLimit-* (see Rate limits & quotas)

HTTPType · codeRetryGateway behavior

400invalid_requestnoMalformed body or parameter; param names the field. A provider 4xx arrives as code provider_http_4xx

400invalid_requestcode: unsupported_parameternoA body field the route does not list (voice cloning, callback_url, previous_job_id, provider routing or account fields) is refused, never forwarded

400invalid_requestcode: approval_requirednoManagement API: the mutation is gated by an approval policy and now waits for a decision; error.approval_request_id names the request

401authenticationnoKey missing, malformed, unknown or revoked (code invalid_api_key); same answer for every case

402insufficient_fundsnoHard stop before dispatch: no wallet or the hold was refused; nothing is charged

402insufficient_fundscode: budget_exceedednoA blocking budget in scope is exhausted (spent + estimate > amount); param is "budget" and the message names it. Nothing is sent, nothing is charged

403permissionnoYour role lacks the permission (management API); an OAuth token outside its scopes gets code insufficient_scope

404not_foundnoModel not available to your organization, or unknown resource — never a hint that it exists

409invalid_requestcode: idempotency_key_reusednoThe Idempotency-Key was already used with a different request body; param is "Idempotency-Key"

409invalid_requestcode: idempotency_in_progressyesThe original request with this Idempotency-Key is still running; retry after about a second and you get its stored response

422capability_unsupportednoStrict-mode parameter rejection, or code no_eligible_route when hard constraints eliminate every endpoint; no provider contacted

422capability_unsupportedcode: operation_unsupportednoThe model is not served on this route (an image model sent to /v1/chat/completions, for example); the message names the route that serves it

429rate_limitcode: rate_limityesYour key or organization bucket is empty: param is "requests" or "tokens", Retry-After and X-RateLimit-* say when; nothing is charged and no request is recorded

429rate_limitcode: provider_rate_limityesA provider rate-limited the attempt: Retry-After set, then fallback to the next planned attempt within your constraints

500internalnoUnexpected failure; unhandled ones carry retriable: true. Quote request_id to support

502provider_erroryesProvider returned an error; retried on the next planned attempt

503overloadedyesProvider 502/503/504 or timeout; retried on the next planned attempt. Endpoints whose circuit is open are left out of the plan

Idempotency

Send Idempotency-Key on any inference call. The key is claimed per organization before the request is written and kept for 24 hours. A second call with the same key and the same body is a replay: the stored status and body come back with Idempotency-Replayed: true and the original's X-Request-Id, an originally streamed request is replayed as a compact SSE stream ending in the same final frame, and no rate-limit token, wallet hold or charge is consumed. The same key with a different body is 409 code: "idempotency_key_reused" (param: "Idempotency-Key"); while the original is still in flight it is 409 code: "idempotency_in_progress" with retriable: true — retry after about a second. Only successful responses are stored, so a request that failed may be retried with the same key.

POST /v1/chat/completions
Idempotency-Key: order-8812-summary          # any string unique to the operation, per organization

# first call → 200, X-Request-Id: req_01J9F3KJ…
# same key + same body within 24 h → 200, the stored body, plus
Idempotency-Replayed: true
X-Request-Id: req_01J9F3KJ…                   # the original request

# same key + different body → 409 idempotency_key_reused
# original still running        → 409 idempotency_in_progress

Partial streams that disconnect are metered for the usage observed and reconciled against the provider's final report.

Errors

#Error shape

#Idempotency

Error shape

Idempotency