Errors

All error responses use a consistent shape:

{
  "error": {
    "message": "Invalid API key",
    "type": "auth_error"
  }
}

Error types

HTTP	type	Reason	What to do
400	invalid_request_error	Invalid JSON, missing field, unknown parameter	Fix the request and check the schema
401	auth_error	Invalid or revoked key	Generate a new key in the dashboard
402	insufficient_balance	Credit balance is too low	Top up from Dashboard > Billing
403	forbidden	The model is not available for this account	Verify model access
404	model_not_found	Unknown model value	Check the canonical ID (provider/model)
413	request_too_large	Context window exceeded	Shorten the messages content
429	rate_limit_exceeded	Rate limit hit	Retry with exponential backoff
500	internal_error	Gateway internal error	Retry after a short delay
502	provider_error	Provider-side failure	Often transient, retry
503	provider_unavailable	Provider unreachable	Retry later
504	timeout	Request timed out	Request fewer tokens or try streaming

Retry strategy

Retry only for 429, 500, 502, 503, 504.
Backoff: exponential + jitter.
Max retry: 3.

Example (Python):

import time, random
from openai import OpenAI, APIStatusError

RETRIABLE = {429, 500, 502, 503, 504}

def call(client, payload, attempt=0):
    try:
        return client.chat.completions.create(**payload)
    except APIStatusError as e:
        if e.status_code in RETRIABLE and attempt < 3:
            time.sleep(2 ** attempt + random.random())
            return call(client, payload, attempt + 1)
        raise

When implementing retries, also account for client-side timeouts, broken connections, and duplicate sends.