Errors
Errors
Errors use the OpenAI error envelope, with a machine-readable type.
json
{
"error": {
"message": "balance too low for this request: top up to continue",
"type": "insufficient_balance"
}
}| Status | Type | What it means |
|---|---|---|
| 400 | invalid_request | Malformed JSON, or model omitted. |
| 401 | invalid_api_key | Key missing, malformed, or revoked. |
| 402 | insufficient_balance | Your balance is empty. Deposit to continue. |
| 403 | model_not_allowed | This key has an allowlist that excludes the requested model. |
| 404 | model_not_found | Unknown model id, or a model no longer offered. |
| 429 | rate_limit_exceeded | This key's per-minute limit was exceeded. Back off and retry. |
| 502 | upstream_error | The upstream model failed. Nothing was billed. |
| 503 | upstream_error | Capacity temporarily unavailable. Retry shortly. |
Retry guidance
Retry 429, 502 and 503 with exponential backoff. Do not retry 400, 401, 403 or 404, as they will fail identically until you change the request. Treat 402 as an alert to top up rather than a transient fault.
python
import time
from openai import OpenAI, APIStatusError
def call(**kw):
for attempt in range(5):
try:
return client.chat.completions.create(**kw)
except APIStatusError as e:
if e.status_code in (429, 502, 503) and attempt < 4:
time.sleep(2 ** attempt)
continue
raiseA failed upstream request costs you nothing. We only deduct balance once a request settles with a usage report.