Error Codes

On error, the endpoint returns the standard OpenAI error structure:

{
  "error": {
    "message": "a specific error description",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

HTTP status codes

HTTP status	Meaning	Common causes & handling
400	Bad request	Missing parameters, malformed JSON, or values out of a model's limits. Fix the body per the message field
401	Unauthorized	Missing, wrong, or disabled token. Check the Authorization header
403	Forbidden / out of quota	Token quota exhausted, model not in the allowed group, or IP not allowed. Check the token settings and balance in the console
404	Not found	Misspelled model name or non-existent path. Verify the model ID with /v1/models
422	Validation failed	Body is well-formed but a value is invalid. Adjust per message
429	Too many requests	Rate limit hit. Retry with exponential backoff
500	Server error	Internal platform error. Retry later; contact support if it persists
503	Upstream unavailable	Upstream channel is fluctuating. Retry later or switch models if it persists

Error types (type)

type	Description
invalid_request_error	Invalid request parameters
authentication_error	Authentication failed
permission_error	No permission to access the resource
not_found_error	Resource does not exist
rate_limit_error	Rate limited
api_error	Internal API error
overloaded_error	Service overloaded

Common error codes (code)

code	Description
invalid_api_key	Invalid API key
model_not_found	Model does not exist or is not accessible
context_length_exceeded	Input exceeds the model's maximum context length
max_tokens_exceeded	max_tokens exceeds the model's limit
insufficient_quota	Insufficient account balance
rate_limit_exceeded	Request frequency too high
content_filter	Content blocked by the safety filter

Retry advice

For 429 and 5xx errors, use exponential backoff:

import time

def chat_with_retry(client, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"request failed, retrying in {wait}s... ({e})")
            time.sleep(wait)

WARNING

For client errors like 400, 401, 403, and 404, retrying is pointless — check the request parameters or token configuration instead.