Errors

The error envelope, every code a client should handle, and what to retry.

The envelope

Every /v1 error is an OpenAI-shaped envelope with a stable code. Branch on code (and on the message prefix for quota errors), never on message text. /v1/messages uses Anthropic's envelope and /v1beta Google's, at the same statuses. Unknown /v1 paths: 404 not_found.

POST/v1/chat/completionsPOST/v1/messages
{
  "error": {
    "message": "The requested model alias is not granted to this identity.",
    "type": "permission_error",
    "code": "model_not_granted",
    "param": null
  }
}

Request errors (fix, then resend)

CodeHTTPMeaning and fix
invalid_json400Body is not JSON
invalid_request400Malformed; read the message
invalid_parameter400A field is invalid; param names it
unsupported_parameter400The route rejects one field (for example temperature on a reasoning-only route); drop it
unsupported_capability400The model does not serve a whole capability (tools, a modality, reasoning); pick another model
capability_requires_payment / _purchase400The feature in param needs card verification or a purchase on this model
refusal400Provider refused on policy; refusal_reason is one of cyber_policy, cbrn, content_policy, recitation, data_inspection, unspecified. Change the request or model
context_length_exceeded400Prompt plus output budget exceeds the context window; trim or compact
content_filter400Blocked by your org's guardrail policy
provider_credential_rejected / provider_account_quota400Your own BYOK key was rejected or its provider account is out of quota; fix it at the provider
previous_response_not_found400Continuation unknown or expired; resend the full conversation
zdr_continuation_disabled400Continuation under ZDR routing; resend the conversation or opt in
invalid_key401Fix the Authorization header
model_not_granted403Not a slug your org can call (or every route removed by your data controls); use an id from /v1/models
model_location_not_supported403Request location outside the model maker's supported regions
idempotency_conflict409Same Idempotency-Key, different body; use a new key
{"error": {"code": "unsupported_parameter", "param": "temperature",
  "type": "invalid_request_error", "message": "..."}}

Account, quota and rate limits

402 needs an account action. insufficient_quota clears only when you add credits or raise a limit. rate_limit_exceeded and admission_capacity_exceeded clear on their own: wait Retry-After. The message prefix says which limit fired; it names your tier and how to raise it (Rate limits).

CodeHTTPMessage prefixes
card_required, email_unverified402Complete the $1 card verification (or email proof); BYOK keeps working
org_under_review402Organization quarantined; contact support. Payment does not lift it
insufficient_quota429insufficient_credits, key_daily_cap (also _weekly_, _monthly_, _yearly_), promo_byok_only, model_requires_payment, model_requires_purchase
rate_limit_exceeded429org_rate_limit, org_token_rate_limit (_hour, _day), per-location limits
free_limit_reached429A free allowance is spent; the message names the token limit and reset
free_tier_requires_payment402The free tier needs a card or the $1 verification
promotion_ended402One-time notice on the plain slug of a model that is free only as <slug>:free; send :free, or resend to pay from credits
admission_capacity_exceeded429Too many of your org's requests waiting at once

Requests on your own provider keys are never counted against org rate limits.

GET/api/v1/credits
HTTP/2 429
retry-after: 12

{"error": {"type": "rate_limit_error", "code": "rate_limit_exceeded",
  "message": "org_rate_limit: ..."}}

Upstream and gateway errors

CodeHTTPMeaning
unavailable_route429 / 503Throttled or no healthy route
gateway_overloaded429Replay window full
request_cancelled499Client disconnected
all_routes_failed502Every route failed ("provider stream failed" = died before output)
gateway_unavailable503Model temporarily unavailable
provider_output_too_large502Lower max output tokens
gateway_draining503Instance draining; retry after 10 s
deadline_exceeded503No first byte in time, or the overall deadline passed
internal_error500Unexpected
empty_completion200Header x-gateway-warning: empty_completion: the model returned nothing on every route; change the last turn or model, do not resend unchanged
HTTP/2 200
x-gateway-warning: empty_completion

What to retry

StatusAction
429 rate_limit_exceeded, admission_capacity_exceeded, free_limit_reachedWait Retry-After, retry
429 insufficient_quotaDo not retry; add credits or raise the named limit
502, 503, 504, 500Retry with exponential backoff
400, 401, 403, 409Fix the request first
402Do the account action the message names
200 empty_completionChange the request

Delivery is at least once: use Idempotency-Key on Chat Completions and Responses so a retry cannot bill twice. Claude Code shows some of these differently; see Coding agents.

import random, time, uuid, openai

RETRYABLE = {"rate_limit_exceeded", "admission_capacity_exceeded"}

def call(messages, attempts=5):
    key = str(uuid.uuid4())
    for i in range(attempts):
        try:
            return client.chat.completions.create(
                model="gpt-6-luna", messages=messages,
                extra_headers={"Idempotency-Key": key})
        except openai.APIStatusError as e:
            code = (e.body or {}).get("error", {}).get("code") if isinstance(e.body, dict) else None
            if e.status_code >= 500 or (e.status_code == 429 and code in RETRYABLE):
                wait = float(e.response.headers.get("retry-after", 2 ** i))
                time.sleep(wait + random.random())
                continue
            raise