Error Codes and Troubleshooting

Identify What Failed

1. Record the actual HTTP status, request method, and path. The HTTP status and application error code describe different layers; do not substitute one for the other.
2. Read error fields according to the protocol you called. Native, OpenAI, Claude, and Gemini responses do not all share the same structure.
3. For streaming requests, also inspect error events and completion state. For asynchronous jobs, inspect the job status. HTTP 200 does not guarantee successful generation.
4. Use the table below to fix the request or decide whether to retry. message is explanatory text, not a stable enum; do not branch on its wording.

Platform Error Code Enum

This is the complete enum of platform application error codes. Names are reference labels; response code values are numbers. “Common HTTP” is a troubleshooting guide, not a fixed mapping for every endpoint. Use the actual HTTP status and response body. A code passed through from upstream may not belong to this enum.

HTTP 429 alone cannot reliably distinguish rate limits from concurrency limits. Make that distinction only when an explicit numeric error code is available. Check model identifiers in the model list; do not rewrite model values yourself.

Read Errors by Protocol

The examples below show common platform-generated structures, not a single format guaranteed for every failure. Authentication failures may be returned by different processing layers, and upstream passthrough responses may retain their own structures, string codes, or types. Identify the actual response shape before parsing it. If it is unrecognized, preserve the original fields and HTTP status instead of forcing a conversion.

Native Platform APIs

Usually read error.code and error.message. requestId may be absent.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Some errors may use top-level code and message. Clients should tolerate this difference and must not treat the absence of an error object as proof of success. Parameter validation responses may also lack a numeric error code. Treat a missing code as unknown rather than inventing one.

OpenAI-Compatible APIs

Common platform-generated errors use top-level code, message, and type; they are not necessarily wrapped in error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type is a protocol category; code is the platform numeric error code in this structure. api_error alone does not determine whether a retry is appropriate. Upstream passthrough and streaming errors may contain a nested error; handle the actual protocol response. See Chat Completions and Responses.

Claude-Compatible APIs

In the common structure, the top-level type is error, the specific category is error.type, and the description is error.message. This structure does not include a platform numeric code. Do not invent one.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

The platform locally generates the following Claude error types. This is not an exhaustive enum of upstream error types.

See Claude Messages.

Gemini-Style Errors

When you receive a Gemini-style response, read error.code, error.message, and error.status. Here, status is a string category, not an HTTP status or an asynchronous job status.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Platform-generated errors in this shape use platform numeric code values. The local string status mapping is below; this is not an enum of all upstream statuses.

503 takes precedence and uses UNAVAILABLE, not INTERNAL. Upstream responses may use different code and status semantics. Do not apply the platform error code table to every Gemini numeric code.

Retry Safely

Honor a valid Retry-After header when present. Do not assume every error includes it. Automatically retrying a non-idempotent generation request may execute it again and incur additional charges. This page does not promise general idempotency-key support; adding Idempotency-Key yourself does not guarantee deduplication.

If you already have a jobId, query that job before creating another. If you have no jobId and the outcome is uncertain, preserve the request identifier and timestamp for investigation.

Streams and Asynchronous Jobs

SSE Requests

After SSE starts, the HTTP status may remain 200 while a later failure is reported through an error event or payload in the stream. Parse the events and data for the selected protocol and check for normal completion. On an error or unexpected disconnection, do not treat partial text or images as a complete successful result. Event names and payloads differ between endpoints. Do not check only one fixed error field or use “any text received” as your success condition.

Asynchronous Jobs

A creation response containing data.jobId means the request was accepted, not that generation is complete. A successful HTTP response when querying a job means the query succeeded. You must still inspect the job data.status:

• PENDING, CONNECT, PROCESSING: continue polling as described in the Jobs documentation.
• COMPLETED: read outputResult.
• FAILED, CANCELLED: stop polling and preserve the job ID and sanitized response information for investigation.

Failure details may appear in data.outputResult.error. This field is optional and is not guaranteed for every failed job. Use Jobs only when the creation response explicitly returns a jobId. Do not apply job polling to endpoints that return results directly through JSON or SSE.

Diagnostics for Users and AI Assistants

Provide the following sanitized information to support or an AI assistant. Use unknown for absent fields; use unknown for HTTP status if no HTTP response was received. Preserve field paths and original value types, for example error.code: 10000 (number) or error.code: "invalid_api_key" (string). Do not automatically convert a string code to a platform numeric code or invent missing fields from message, HTTP status, or model names.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Read requestId from the response body or the X-Request-ID response header when available. Keep jobId as a string to avoid losing precision with long numbers. Provide only minimal, sanitized request parameters. Remove API Keys, tokens, cookies, full authentication headers, personal information, private prompts, and input file contents. Remove URL query parameters and input or output URLs containing signatures or access credentials. Do not paste complete request logs without reviewing them.

AI assistants should distinguish observed fields from possible causes and identify missing information. Insufficient evidence must not be treated as proof that a request succeeded, did not execute, or incurred no charge.