Handle API errors
Read a public error, choose a safe action, and prepare support evidence.
Last updated on
On failure, preserve the HTTP status and API response before reading the public code. Do not replace the exact response with an assumption based on status alone because the same status can require different actions.
Read an OpenAI-compatible error
A normal Chat Completions failure has an error object. For example, temporary model unavailability uses this public shape:
{
"error": {
"code": "MODEL_NOT_AVAILABLE",
"message": "The selected model is temporarily unavailable. Please try again.",
"param": null,
"type": "server_error"
}
}Use error.code for client decisions, error.message for readable diagnostics, error.param for the related field, and error.type for the error class. Do not parse message text when a public code is available.
Some model-validation failures also expose stable top-level code and model fields. Billing failures can use stable top-level fields too: insufficient balance reports current and required amounts, while a key limit reports API_KEY_SPEND_LIMIT_EXCEEDED, its period, amounts, and resetAt. Preserve the actual response body instead of assuming every error uses one nested shape.
Branch on HTTP status and public code rather than private causes.
Choose an action from status and code
| Signal | What to inspect | Action |
|---|---|---|
HTTP 400 | error.code, error.param, model, and request body | Correct the format, context, output limit, or unsupported capability. Do not repeat the unchanged request. |
HTTP 401 | Bearer header and key state | Use a valid key from the active workspace. Revoke and replace a lost or exposed key. |
HTTP 402 | Available balance and active reservations | Let active reservations complete or release and check available balance again before you reduce the request or top up the workspace. |
HTTP 403 | Public code and workspace role | Correct access permissions. Only when the code is FIRST_TOP_UP_REQUIRED, use the returned topUpUrl for the first real top-up. |
HTTP 429 | Top-level code and resetAt when present | For API_KEY_SPEND_LIMIT_EXCEEDED, wait for resetAt or change the limit; retry a transient limit only under the limits and retries guidance. |
HTTP 5xx | Public code and whether output has started | Follow the bounded retry rules. After any output, do not start an automatic duplicate. |
| No HTTP response | Client network, DNS, TLS, cancellation, and whether partial output arrived | No output does not confirm that the request was not accepted. Check Usage, the exact time, and model, then make an explicit decision under the retry rules. |
FIRST_TOP_UP_REQUIRED and topUpUrl are shipped fields for a model lock in an applicable personal workspace. Do not treat every 403 as a request to add balance because insufficient workspace permission can use the same status.
Distinguish image errors
Image option validation uses MODEL_PARAMETER_COMBINATION_INVALID when a model cannot accept the requested option combination and MODEL_CAPABILITY_METADATA_UNAVAILABLE when capability metadata cannot currently be checked.
Current image execution codes are IMAGE_UPSTREAM_INVALID_REQUEST, IMAGE_UPSTREAM_INVALID_RESPONSE, IMAGE_UPSTREAM_RATE_LIMITED, IMAGE_UPSTREAM_UNAVAILABLE, IMAGE_UPSTREAM_FAILED, IMAGE_ARTIFACT_STORAGE_FAILED, and IMAGE_REQUEST_ABORTED. A client should show the safe message and branch on the public code without exposing an external service name or response.
Prepare safe support evidence
Before contacting support, collect:
- exact HTTP status, public code, and safe message;
- API endpoint and exact model ID;
- request identifier when the client or Usage view supplies one;
- exact time with timezone and the client or tool name and version;
- key name and visible masked prefix;
- a redacted request body only when it is necessary to reproduce the failure.
Do not send secrets or private diagnostics
Never include a complete API key, password, payment credentials, sensitive prompt, external service names, internal routes, or raw external responses. The public error and safe identifiers are sufficient for investigation.