Common AI API error codes and troubleshooting

Separate HTTP status from provider codes

An HTTP status classifies a failure but does not determine its root cause or retry policy. Read the HTTP status, provider type/code/status, message, parameter, retry headers, and request ID together. OpenAI-style errors commonly expose error.type/code/param/message; Anthropic nests error.type/message and adds a top-level request_id; Gemini Interactions uses a string error.code, while GenerateContent uses a numeric code, string status, and optional details. Tencent Cloud API 3.0 can keep HTTP 200 for a business failure, so clients must inspect Response.Error.Code.

Normalize different provider responses into internal log fields instead of inventing one upstream JSON contract that every provider supposedly implements:

Copyhttp_status=429
provider_error_type=rate_limit_error
provider_error_code=rate_limit_exceeded
gateway_request_id=...
provider_request_id=...
retry_after=2s
attempt=1

Common error-code reference

• 400 Bad Request: invalid JSON, required fields, ranges, context, model capability, or safety validation. Correct the request instead of retrying it unchanged.
• 401 Unauthorized: missing, invalid, expired, or revoked credentials, or a failed signature. Fix authentication first.
• 402 Payment Required: Anthropic, DeepSeek, and others use this for billing or balance failures. A retry cannot help before payment is fixed.
• 403 Forbidden: credentials can be valid but lack model, region, resource, or account access, or a model agreement is missing.
• 404 Not Found: wrong host, route, API version, deployment, model, or task. Marketplace labels, native model IDs, cloud deployment names, and gateway aliases are not interchangeable.
• 405 Method Not Allowed and 415 Unsupported Media Type: verify the method, endpoint, and Content-Type. Some platforms also map an unsupported SDK or model capability to 405, so still inspect the provider code.
• 408 Request Timeout: the request or model timed out; 499 Client Closed Request records a client cancellation or disconnect. Execution can be uncertain, so check job state before retrying.
• 409 Conflict: a concurrent update, duplicate creation, or resource-state conflict. Refresh state and resolve the conflict before resubmission.
• 413 Payload Too Large: the HTTP body exceeds a byte limit, commonly because of Base64 media. Compress, resize, split, or use a file reference only when the target route supports it.
• 422 Unprocessable Entity: the request parsed but its parameter semantics are invalid; DeepSeek and Mistral are representative users. Correct the field combination first.
• 424 Failed Dependency: an upstream model or dependency failed. Amazon Bedrock's ModelErrorException is a representative use; inspect its original status and resource instead of blindly retrying every 424.
• 429 Too Many Requests: it can mean RPM, TPM, concurrency, burst traffic, balance, plan, daily quota, free allocation, or platform capacity. Continue classification with the provider code.
• 500 Internal Server Error: a provider internal failure that can also mask an input boundary. Preserve the original error and retry only a confirmed transient case.
• 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout: gateway, regional capacity, upstream availability, or processing timeout. Persistent failures require throttling, a circuit breaker, a verified region or model fallback, or a status-page check.
• 529 Overloaded: Anthropic explicitly uses this for temporary global overload. In a stream, an overloaded_error can arrive after the initial 200 response.

A 429 requires provider-code classification

Honor Retry-After for temporary rate limits when it is present. Azure can also return millisecond retry-after-ms. Without a usable hint, apply exponential backoff with random jitter, a maximum attempt count, and an overall deadline. Failed attempts can consume quota, so a hot retry loop delays recovery.

Credits, plan expiry, spend caps, daily quota, and exhausted free allocation require payment, renewal, a quota change, or a reset; fast retries cannot repair them. Representative differences include DeepSeek using 402 for insufficient balance; Kimi placing overload, balance, and RPM/TPM under 429; Zhipu distinguishing arrears, account throttling, model congestion, and plan caps through separate business codes under 429; and Cloudflare using 3036 for exhausted free Neurons versus 3040 for no available data center. Match stable codes, not message strings that can be reworded or localized.

Provider protocol differences

• OpenAI: preserve error.type and error.code; distinguish transient 429 from credit, organization, or project spend limits. Official SDKs can already retry connection failures, 408, 409, 429, and 5xx errors, so avoid accidental retry multiplication.
• Anthropic: it additionally defines 402, 409, and 529; every response has a request-id, and error bodies include request_id. Error types and stream events can expand, so parsers must tolerate unknown values.
• Gemini: Interactions and GenerateContent use different error models and fields. Interactions separates rate_limit_exceeded from quota_exceeded; a GenerateContent safety block, finish reason, or empty candidate set might not be an HTTP error.
• Model Studio, Kimi, Zhipu, and Baidu Qianfan: they combine HTTP status with finer business codes. The same 400 or 429 can identify parameters, safety, credits, plans, hard quota, or transient congestion. Native Model Studio responses often contain request_id, but that does not prove every compatibility route shares the same shape.
• Tencent Hunyuan native protocol: a normally processed request often returns HTTP 200, with business failure in Response.Error.Code. Branch on the stable code rather than the changeable message.
• Amazon Bedrock: SDKs expose exception names such as ValidationException, ModelTimeoutException, ModelErrorException, and ThrottlingException; 424, 429, and 503 have different causes.
• Azure OpenAI: a 429 can reflect deployment TPM/RPM or temporary capacity. Prefer retry-after-ms and x-ratelimit-*; do not treat a content-policy signal as a transient 400.
• Cloudflare Workers AI and Mistral: Cloudflare needs its internal numeric code to distinguish free allocation from capacity. Mistral classifies 429/500/502/503/504 as transient backoff candidates, while request, authentication, and access failures still require correction.

HTTP 200 can still end in failure

Once SSE or NDJSON starts, the HTTP status normally cannot change. OpenAI Responses, Anthropic Messages, and Gemini Interactions can send error events in the stream. Gemini GenerateContent also requires checking promptFeedback, candidate finishReason, and candidate presence. A 200 or 202 from an asynchronous image, video, or Batch create call means accepted, not successfully completed.

Parse complete events according to protocol boundaries, tolerate unknown event types, and mark success only after an explicit completion event or terminal state. Do not automatically replay a side-effecting or potentially billed create request after a broken stream; determine upstream state from the job ID, idempotency key, and logs first.

Retain request IDs and minimal evidence

This gateway returns X-Oneapi-Request-Id. Also preserve provider x-request-id, request-id, apim-request-id, x-amzn-requestid, or body request_id/RequestId values when present. Do not confuse an asynchronous job ID with a universal synchronous trace ID, and do not assume every provider supplies the same header.

A diagnosable failure includes UTC time, gateway request ID, provider request ID, path, model, HTTP status, business code, streaming mode, attempt count, and elapsed time. Mask all but a few key characters and collect payloads, files, and personal data only when necessary. Never send a complete key or sensitive input in a support ticket.

Production retry and fallback rules

• Do not automatically retry 400/401/402/403/404/405/413/415/422, safety, billing, plan, or hard-quota errors. Resubmit only after the root cause changes.
• For 409, refresh and resolve state. For 408/499, determine whether execution already happened; retry only idempotent or safely deduplicated operations.
• Apply bounded exponential backoff, random jitter, an overall deadline, and concurrency caps only to transient 429, network failures, and confirmed transient 500/502/503/504/529 errors.
• Honor a valid Retry-After and check whether the SDK already retries. Add circuit breakers, verified model fallbacks, and alerts to prevent retry storms.
• Use a business idempotency key for asynchronous creation. Query after a timeout and route uncertain outcomes into compensation or manual review instead of blindly repeating a billed action.

Minimal reproduction and escalation

Re-run the quickstart curl with the same base URL, gateway key, endpoint, and model, then add media, tools, and optional fields one at a time. If curl succeeds, capture the SDK's redacted effective URL, version, proxy, timeout, and retry settings. If minimal curl fails, contact support with request IDs, time, path, model, status, and the provider error object.