Errors

Every error — validation, billing, upstream — uses one envelope the OpenAI SDKs already parse. The same broken request always gets the same error, so retry logic can trust what it reads.

The envelope

{
  "error": {
    "message": "max_tokens (32768) exceeds the limit for your organization (16384).",
    "type": "invalid_request_error",
    "param": "max_tokens",
    "code": "max_tokens_exceeds_cap",
    "metadata": {}
  }
}

• type — stable taxonomy for branching (matches the table below).
• code — the precise machine-readable case.
• param — the offending field, when one exists.
• metadata — extra machine data on some errors, e.g. the available balance on a 402.

All error codes

Errors inside a stream

After streaming starts, HTTP is already 200 — failures arrive as a final chunk with finish_reason: "error" carrying this same envelope in an error field. Sample and handling code: Streaming.

Retry guidance

• Retry with backoff: request_timeout, upstream_error, no_capacity, and 429s with retry-after — the OpenAI SDKs already do this.
• Fix before retrying: every 400/401/403/404/413/422 — the request itself is the problem.
• Act, don't retry: insufficient_credits (top up) and daily_budget_exceeded (raise the budget or wait for 00:00 UTC).

Catching the 402 in your code

The OpenAI SDKs have no dedicated exception class for 402 — it surfaces as the generic APIStatusError (Python) / APIError (Node), so a handler written only for RateLimitError or AuthenticationError will miss it. Branch on the status or on error.code:

# Python
import openai
try:
    resp = client.chat.completions.create(...)
except openai.APIStatusError as e:
    if e.status_code == 402:
        print("Out of credits:", e.body["error"]["message"])  # includes balance + top-up link
    else:
        raise

// Node
try {
  const resp = await client.chat.completions.create({...});
} catch (err) {
  if (err instanceof OpenAI.APIError && err.status === 402) {
    console.error('Out of credits:', err.error?.message);
  } else throw err;
}