Browse the docsError codes

Error codes

Every failure returns the same envelope: a stable machine-readable code, a human-safe message, and the request_id to quote in a support ticket. Branch on code, never on the message text.

HTTP	Code	What went wrong	How to fix it
401	invalid_api_key	Missing, malformed, or revoked key, or an inactive account.	Fix or replace the key.
402	insufficient_credits	The account is out of credits.	Top up, then resend.
403	permission_denied	This key is not allowed to perform the action.	Check the key's scope and workspace.
404	model_not_found	Unknown model name in the request.	Use `chitragupta`.
405	method_not_allowed	Wrong HTTP method for this route.	All completion routes are `POST`.
409	idempotency_conflict	An `Idempotency-Key` was reused with a different body.	Use a new key, or resend the exact original body.
413	file_too_large	The uploaded file exceeds the size limit.	Compress the file before encoding.
413	page_limit_exceeded	Too many pages and images combined.	Split into smaller requests.
422	invalid_request	Malformed body, or `max_tokens` above the cap.	Fix the payload.
422	system_message_not_allowed	A `system` message was sent; the model uses a fixed prompt.	Move the instruction into the `user` message.
422	images_not_allowed	An image was sent to a text-only model.	Use a vision-capable model.
429	rate_limit_exceeded	Too many requests per second, or too many in flight on this key.	Honor the `Retry-After` header.
429	quota_exceeded	The key or account hit its usage quota.	Wait for the reset or raise the quota.
500	internal_error	Unexpected server-side failure.	Retry with exponential backoff.
502	inference_failed	The model returned an invalid response.	Retry once; if it persists, log the `request_id`.
503	provider_unavailable	Inference capacity is temporarily unavailable.	Retry with exponential backoff.
504	inference_timeout	The model took too long.	Retry with backoff, or send fewer pages.

# See the request_id even on an error:
try:
    r = client.chat.completions.create(model=MODEL, messages=[{"role": "user", "content": "hi"}])
    print(r.id.replace("chatcmpl-", ""))
except Exception as e:
    print(type(e).__name__, getattr(e, "status_code", "?"), getattr(e, "body", None))