Errors come back in the OpenAI error envelope, so SDK error handling works unchanged. The message field carries the specific reason; the status tells you whether retrying is worth anything.
Error shape
{
"error": {
"message": "insufficient user quota",
"type": "new_api_error",
"code": "insufficient_user_quota"
}
}Status codes
| Status | Meaning | What to do |
|---|---|---|
401 | Key missing, malformed, revoked or expired | Check the Authorization header, then reissue the key |
403 | Key is valid but not allowed this model, or quota is exhausted | Check the key's model allowlist and the account balance |
404 | No channel serves the requested model | Call GET /v1/models for names this instance actually serves |
429 | A configured rate limit was exceeded | Back off and retry with jitter |
5xx | Upstream provider failed or timed out | Retry; failover to another channel is automatic where one exists |
Retrying
Retry 429 and 5xx with exponential backoff and jitter. Do not retry 401 or 403 — they are decisions about your key, not transient conditions, and hammering them will not change the answer.