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.
/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)
| Code | HTTP | Meaning and fix |
|---|---|---|
invalid_json | 400 | Body is not JSON |
invalid_request | 400 | Malformed; read the message |
invalid_parameter | 400 | A field is invalid; param names it |
unsupported_parameter | 400 | The route rejects one field (for example temperature on a reasoning-only route); drop it |
unsupported_capability | 400 | The model does not serve a whole capability (tools, a modality, reasoning); pick another model |
capability_requires_payment / _purchase | 400 | The feature in param needs card verification or a purchase on this model |
refusal | 400 | Provider refused on policy; refusal_reason is one of cyber_policy, cbrn, content_policy, recitation, data_inspection, unspecified. Change the request or model |
context_length_exceeded | 400 | Prompt plus output budget exceeds the context window; trim or compact |
content_filter | 400 | Blocked by your org's guardrail policy |
provider_credential_rejected / provider_account_quota | 400 | Your own BYOK key was rejected or its provider account is out of quota; fix it at the provider |
previous_response_not_found | 400 | Continuation unknown or expired; resend the full conversation |
zdr_continuation_disabled | 400 | Continuation under ZDR routing; resend the conversation or opt in |
invalid_key | 401 | Fix the Authorization header |
model_not_granted | 403 | Not a slug your org can call (or every route removed by your data controls); use an id from /v1/models |
model_location_not_supported | 403 | Request location outside the model maker's supported regions |
idempotency_conflict | 409 | Same 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).
| Code | HTTP | Message prefixes |
|---|---|---|
card_required, email_unverified | 402 | Complete the $1 card verification (or email proof); BYOK keeps working |
org_under_review | 402 | Organization quarantined; contact support. Payment does not lift it |
insufficient_quota | 429 | insufficient_credits, key_daily_cap (also _weekly_, _monthly_, _yearly_), promo_byok_only, model_requires_payment, model_requires_purchase |
rate_limit_exceeded | 429 | org_rate_limit, org_token_rate_limit (_hour, _day), per-location limits |
free_limit_reached | 429 | A free allowance is spent; the message names the token limit and reset |
free_tier_requires_payment | 402 | The free tier needs a card or the $1 verification |
promotion_ended | 402 | One-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_exceeded | 429 | Too 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/creditsHTTP/2 429
retry-after: 12
{"error": {"type": "rate_limit_error", "code": "rate_limit_exceeded",
"message": "org_rate_limit: ..."}}Upstream and gateway errors
| Code | HTTP | Meaning |
|---|---|---|
unavailable_route | 429 / 503 | Throttled or no healthy route |
gateway_overloaded | 429 | Replay window full |
request_cancelled | 499 | Client disconnected |
all_routes_failed | 502 | Every route failed ("provider stream failed" = died before output) |
gateway_unavailable | 503 | Model temporarily unavailable |
provider_output_too_large | 502 | Lower max output tokens |
gateway_draining | 503 | Instance draining; retry after 10 s |
deadline_exceeded | 503 | No first byte in time, or the overall deadline passed |
internal_error | 500 | Unexpected |
empty_completion | 200 | Header 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_completionWhat to retry
| Status | Action |
|---|---|
429 rate_limit_exceeded, admission_capacity_exceeded, free_limit_reached | Wait Retry-After, retry |
429 insufficient_quota | Do not retry; add credits or raise the named limit |
| 502, 503, 504, 500 | Retry with exponential backoff |
| 400, 401, 403, 409 | Fix the request first |
| 402 | Do the account action the message names |
200 empty_completion | Change 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