API reference
Error Codes
Interpret HTTP errors and apply the correct fix, retry, and support process.
Successful responses use 2xx. On failure, record the status, error object, request ID, and time, not just the error message.
HTTP status codes
| Status | Meaning | Common causes | Recommended action |
|---|---|---|---|
400 | Invalid request | Invalid JSON, missing fields, wrong types, or unsupported parameters. | Check the request and model capabilities; do not retry unchanged. |
401 | Authentication failure | Missing, invalid, or revoked key; incorrect Bearer format. | Check environment variables and headers; rotate if necessary. |
402 | Insufficient balance | Not enough available account balance. | Review billing and top up before retrying. |
403 | Permission denied | Account or key lacks access to a resource. | Check account status, model permissions, and platform rules. |
404 | Not found | Incorrect endpoint or model ID. | Verify the URL and copy the exact catalog identifier. |
408 | Request timeout | Unstable network or generation exceeds the deadline. | Check payload size and timeouts; retry safe requests a limited number of times. |
429 | Too many requests | Rate, concurrency, or account quota exceeded. | Reduce concurrency, queue requests, and use exponential backoff; request more capacity if needed. |
500 | Internal error | Processing failed on the server or routing node. | Retain the request ID and retry a limited number of times; contact support if persistent. |
502 | Upstream error | Inference node returned an invalid response. | Retry later and retain request details. |
503 | Temporarily unavailable | Too few available nodes, maintenance, or temporary overload. | Back off and check announcements or contact support. |
504 | Gateway timeout | Upstream processing did not finish in time. | Shorten input/output, adjust timeouts, and retry conservatively. |
Error object example
{
"error": {
"message": "Invalid API key",
"type": "authentication_error",
"code": "invalid_api_key"
}
}Fields can vary by error type. Allow additional fields and fall back to the HTTP status when optional fields are missing.
Python exception handling
import openai
try:
response = client.chat.completions.create(
model="qwen-turbo",
messages=[{"role": "user", "content": "Hello"}],
)
except openai.AuthenticationError:
print("The API key is invalid or revoked")
except openai.RateLimitError:
print("Requests are too frequent; back off before retrying")
except openai.APITimeoutError:
print("The request timed out")
except openai.APIConnectionError:
print("Cannot connect to the API; check the network")
except openai.APIStatusError as exc:
print("HTTP status:", exc.status_code)
print("Response:", exc.response)Should you retry?
| Error | Automatic retry | Reason |
|---|---|---|
400 / 401 / 402 / 403 / 404 | No | Fix the request, key, balance, or permissions. |
408 / some 429 | Bounded retries | Wait first and use exponential backoff. |
500 / 502 / 503 / 504 | Bounded retries | Usually transient server or upstream failures. |
| Interrupted stream | Caution | A new request may generate different content or duplicate displayed output. |