Errors
Read and handle API errors consistently.
Errors use an OpenAI-compatible envelope. Check the HTTP status first, then use error.code for programmatic handling. Keep request_id when it is present so support can trace a request.
{
"error": {
"message": "Invalid API key",
"type": "authentication_error",
"code": "auth_failed",
"param": null,
"request_id": "…"
}
}Common responses
| Status | Meaning | Client action |
|---|---|---|
400 | Invalid input or unsupported option | Correct the request; do not retry unchanged. |
401 | Missing, invalid, or expired credential | Replace the credential. |
402 | Insufficient balance | Add balance before retrying. |
403 | The key lacks the needed scope | Use a key with the required permission. |
404 | Resource is unavailable to this account | Check the identifier and access. |
413 | Request or upload is too large | Reduce the request or split the file. |
429 | Rate or authentication throttle | Respect Retry-After, then retry with backoff. |
5xx | Temporary API or capacity failure | Retry idempotent work with bounded backoff. |
Do not present raw API messages directly to end users. Map stable error codes to clear product copy and log the request ID separately.