provider,http_status,type,code,retryable,recommended_action,message_semantics,source
anthropic,400,invalid_request_error,compliance_api_not_enabled,false,"Enable the Compliance API (claude.ai > Organization settings > API for Enterprise; Console > Settings > Security toggle for standalone Console org), then resend.",`Compliance API is not enabled for this organization` — key valid but API not enabled (or turned off) for the org/parent; every endpoint returns it.,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,400,invalid_request_error,unknown_query_parameter,false,"Use dot notation for ranges (created_at.gte), `[]` suffix for arrays (activity_types[]), and after_id/before_id/page per endpoint.","`Unknown query parameter: 'created_at[gte]'. Did you mean 'created_at.gte'?` — unrecognized params are rejected, not ignored.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,400,invalid_request_error,invalid_parameter_value,false,Correct the named parameter; respect per-endpoint limit maxima; RFC 3339 timestamps with explicit UTC offset.,"Message starts with the parameter name then the failed constraint, e.g. `limit: Input should be less than or equal to 1000`, `created_at.gte: Input should be a valid datetime…`, `activity_types[].0: Input is not one of the permitted values.`, `created_at.gte: Input should have timezone info`, `created_at.lt must be strictly after created_at.gte.`; tool_use_input_max_bytes/tool_result_max_bytes accept positive int or -1.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,400,invalid_request_error,invalid_pagination_cursor,false,Treat cursors as opaque; copy first_id/last_id/next_page unchanged; on expiry restart without page.,"`Invalid activity_id format: '…'` (activities) / `Invalid pagination cursor for 'after_id'` (chats) / `The page parameter is not a valid cursor for this request.` (local sessions, cursor bound to session+order) / `The page cursor has expired. Restart the walk without a page parameter…` (local session messages, 24 h).",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,401,authentication_error,api_key_invalid,false,Compare stored secret; create a new key if the copy is wrong.,`API key is invalid.` — value does not match a usable Compliance Access Key / Admin API key (truncated/altered).,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,401,authentication_error,api_key_deactivated,false,Re-enable if only disabled; otherwise create a new key and rotate.,`API key has been deactivated.` — key disabled or deleted.,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,401,authentication_error,api_key_expired,false,Create a new key and update the integration.,`API key has expired.` — Admin API key past its expiration (Compliance Access Keys have no expiry).,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,403,permission_error,insufficient_scope_activities,false,"Create a Compliance Access Key with read:compliance_activities, or use an Admin API key created while the Compliance API was enabled.","`Missing required scopes. Got: [...] Needed one of: ['read:compliance_activities', 'read:org_audit']` on GET /v1/compliance/activities.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,403,permission_error,insufficient_scope_org_data,false,Create a new Compliance Access Key with read:compliance_org_data.,"`… Needed one of: ['read:compliance_org_data', 'read:org_audit']` on organizations/roles/groups/settings endpoints; Admin API keys cannot read org metadata.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,403,permission_error,retired_scope_org_settings,false,"Create a new key with read:compliance_org_data, migrate, delete the old key.","`Got: ['read:compliance_org_settings'] Needed one of: ['read:compliance_org_data', 'read:org_audit']` — scope retired 2026-06-30; settings endpoint now needs read:compliance_org_data.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,403,permission_error,insufficient_scope_user_data,false,Use a Compliance Access Key created in claude.ai with read:compliance_user_data.,"`… Needed one of: ['read:compliance_user_data', 'read:org_audit']` on chats/messages/files/projects/sessions/users/group-members; Admin API keys can never hold this scope.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,403,permission_error,insufficient_scope_delete,false,Create a separate key carrying delete:compliance_user_data (keep read and delete keys separate).,`… Needed: ['delete:compliance_user_data']` on DELETE chats/files/projects/documents.,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,request_not_authenticated,false,Send an sk-ant-api01- or sk-ant-admin01- key in x-api-key; check the path against the reference.,"Bare `Not found` — no key, or a key type the Compliance API does not accept (e.g. sk-ant-api03- Claude API key); same body as a non-existent path; any endpoint incl. lists. Exception: organization settings endpoint returns 401 instead.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,chat_not_found,false,Reconcile against claude_chat_created / claude_chat_viewed activities; drop the ID from the queue.,"`Chat conversation not found: '<claude_chat_id>'` — hard-deleted, retention-expired, or outside key scope. User-deleted chats are NOT 404 (listed with deleted_at).",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,file_not_found,false,Reconcile against claude_file_uploaded / claude_file_deleted / claude_chat_deleted activities.,"`File not found: <uuid>` — file missing/deleted (deleting a chat deletes its files); message uses the underlying UUID; applies to metadata, content and delete endpoints, chat files and project files.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,generated_file_or_artifact_not_found,false,"Look up the chat via Get chat messages; if deleted_at set, remove from queue.",`Generated file not found: '…'` (metadata) / `Generated file content not found: '…'` (content) / `Artifact version not found: '…'` (both artifact endpoints) — deleted with their chat.,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,project_not_found,false,Reconcile against claude_project_created / claude_project_deleted activities.,"`No project is found with the provided id.` (detail/attachments/collaborators) / `No project found with provided id, or it has already been deleted.` (DELETE).",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,project_document_not_found,false,List current attachments via GET /v1/compliance/apps/projects/{project_id}/attachments.,"`No project document found with the provided id.` / `…, or it has already been deleted.` (DELETE) — text project documents (claude_proj_doc_) only.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,local_session_not_found,false,"Confirm via the local session list; if absent, transcript is not retrievable.","`Local session not found.` — not readable (other parent org), never existed, ZDR in effect, or fully aged out of retention; no transient form. Malformed non-`clls_` ID → 400.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,local_sessions_not_available,true,Keep queued IDs; retry on the next scheduled run; if persistent contact Anthropic with request-id.,`Local sessions are not available.` — returned on EVERY local-session call incl. the list while the endpoints are unavailable to the parent org; independent of session ID; can be temporary.,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,remote_session_not_found,conditional,Check status via the remote session list; retry after it leaves pending; deleted sessions are gone.,"`Remote session not found.` — `cse_` ID missing/deleted, outside scope, or session still `pending` (no transcript yet). Malformed ID → 400.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,organization_role_or_group_not_found,false,Verify the ID against the corresponding list endpoint.,"`The ""<org_uuid>"" organization does not exist or the requester is not authorized to access it.` / `Role not found.` / `Group not found.`",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,404,not_found_error,organization_settings_not_available,false,"Verify against List organizations; if a known-good ID still 404s, contact your Anthropic representative.","`organization `<uuid>` not found in this organization's hierarchy` — org not a linked child, invalid UUID, or settings endpoint not yet enabled for the parent (same body on purpose).",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,409,invalid_request_error,project_has_attached_chats,false,"List chats with user_ids[] + project_ids[], delete or detach each, retry the project delete.","`The ""<claude_proj_id>"" project cannot be deleted as it has chats attached to it. Delete or detach all chats, and try deleting the project again.` (type is invalid_request_error — distinguish by 409).",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,429,rate_limit_error,compliance_rate_limit_exceeded,true,Wait `retry-after` seconds (fallback exponential backoff 1 s → 60 s); do NOT advance the cursor. Headers: anthropic-ratelimit-requests-limit/-remaining/-reset.,`Compliance API rate limit of 600 requests per minute per parent organization has been exceeded…` — shared budget across all keys/linked orgs/endpoints; remote-session endpoints carry a second budget (its 429 has retry-after: 1 always).,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,500,api_error,,true,"Retry with exponential backoff; if persistent, contact support with request_id.",Unexpected internal error.,https://platform.claude.com/docs/en/api/errors
anthropic,502/503/504/529,,,true,Retry with exponential backoff; check status.anthropic.com. Exception: some local-session 503s are not transient (see overloaded_error).,Transient upstream/overload errors.,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,503,overloaded_error,local_sessions_index_unavailable,true,Retry with backoff; do not advance page cursor.,`The local-sessions index is temporarily unavailable. Try again shortly.` — transient.,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,503,overloaded_error,local_sessions_captured_content_unavailable,conditional,"Retry with backoff; if it keeps recurring for a CMEK org, check the key in your KMS and stop walking that org's transcripts.",`Captured content is temporarily unavailable. Try again shortly.` — usually transient; persistent for CMEK orgs whose key is disabled/revoked/unreachable (never reported as not_captured).,https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,503,overloaded_error,local_sessions_retention_overrides_unavailable,conditional,Do not hold the walk open: narrow created_at window or skip the session and retry on a later run (restart without page).,"`The local-sessions index cannot currently evaluate retention overrides for this page/session. Try again later.` — depends on the org's data/settings, can persist.",https://platform.claude.com/docs/en/manage-claude/compliance-errors
anthropic,400,invalid_request_error,,false,"Fix the request (message names the field, e.g. 'max_tokens: Field required'). Do not retry unchanged.","Malformed/invalid request; also used for other 4xx not listed, org/workspace spend limit reached, invalid anthropic-version or anthropic-beta value, unsupported parameter for the model.",https://platform.claude.com/docs/en/api/errors
anthropic,401,authentication_error,,false,Check the key / auth header. Live: 'invalid x-api-key'; anthropic-organization-id header absent on 401.,"API key malformed, revoked, expired (or bad AWS SigV4 on Claude Platform on AWS).",https://platform.claude.com/docs/en/api/errors
anthropic,402,billing_error,,false,Fix payment details in Console (or AWS Marketplace).,Billing/payment problem.,https://platform.claude.com/docs/en/api/errors
anthropic,403,permission_error,,false,Check organization access / workspace settings. Does NOT mean the endpoint doesn't exist.,Key lacks permission for the resource (workspace/org settings).,https://platform.claude.com/docs/en/api/errors
anthropic,404,not_found_error,,false,"Check path/ids; for models, use GET /v1/models.","Resource not found: unknown path, unknown resource id, or unknown model ('model: <id>').",https://platform.claude.com/docs/en/api/errors
anthropic,409,conflict_error,,true,Resolve the conflict then retry (SDKs retry 409 by default).,"Request conflicts with resource state (concurrent modification, uniqueness).",https://platform.claude.com/docs/en/api/errors
anthropic,413,request_too_large,,false,Shrink the request (use Files API / batches).,"Body exceeds the size limit: Messages & count_tokens 32 MB, Batches 256 MB, Files 500 MB (returned by Cloudflare before the API).",https://platform.claude.com/docs/en/api/errors
anthropic,422,unprocessable_entity (SDK class only),,false,Treat like 400.,Not in the HTTP error list of the docs; SDKs map 422 to UnprocessableEntityError.,https://platform.claude.com/docs/en/api/errors
anthropic,429,rate_limit_error,,true,"Honor `retry-after` when present, exponential backoff with jitter; if no retry-after and message mentions spend cap, stop retrying and raise the cap. Ramp traffic gradually.","Rate limit (RPM/ITPM/OTPM), monthly tier spend cap (no retry-after header, keeps failing), acceleration limit, or Claude Code workspace spend limit.",https://platform.claude.com/docs/en/api/errors
anthropic,504,timeout_error,,true,Use streaming or the Batches API for long requests; retry.,Request timed out while processing.,https://platform.claude.com/docs/en/api/errors
anthropic,529,overloaded_error,,true,Retry with backoff; Priority Tier reduces occurrence. Handle the SSE `error` event.,API temporarily overloaded (all users); can also arrive as a mid-stream `error` event after HTTP 200.,https://platform.claude.com/docs/en/api/errors
anthropic,,streaming error event,,true,"Abort the stream, then retry (SDKs raise; Claude 4.6+: resume by sending partial text in a user message asking to continue).","After HTTP 200 the stream may emit `event: error` with {type: error, error:{type, message}} (e.g. overloaded_error).",https://platform.claude.com/docs/en/build-with-claude/streaming
anthropic,,x-should-retry header,,,Respect it when present.,Observed on every error response: `x-should-retry: false` for 4xx; SDKs consult this header (true/false) before their status-based retry decision.,https://platform.claude.com/docs/en/api/errors
anthropic,200,stop_reason: refusal,,false,"Retry on a fallback model (server-side `fallbacks` beta or client-side), redeem fallback_credit_token.",Not an error: safety classifiers stopped generation; HTTP 200 with stop_details.category.,https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
anthropic,,tool result error codes,,,Inspect the result block; `too_many_requests`/`unavailable` are transient.,"Server-tool result blocks carry `error_code` instead of HTTP errors: web_search invalid_tool_input|unavailable|max_uses_exceeded|too_many_requests|query_too_long|request_too_large; web_fetch invalid_tool_input|url_too_long|url_not_allowed|url_not_in_prior_context|url_not_accessible|unsupported_content_type|too_many_requests|max_uses_exceeded|unavailable|content_too_large; code_execution invalid_tool_input|unavailable|too_many_requests|execution_time_exceeded (+output_file_too_large bash, +file_not_found text_editor).",https://platform.claude.com/docs/en/api/messages
anthropic,,SDK retry policy,,,Configure max_retries / timeout; stream for large max_tokens.,"Official SDKs retry connection errors, 408, 409, 429 and >=500 twice by default with exponential backoff (Python: 0.5s initial → 8s max, jitter) honoring retry-after; non-streaming requests time out after 10 min (TS scales up to 60 min by max_tokens/128000 and refuses non-streaming requests expected >10 min: 'Streaming is required for operations that may take longer than 10 minutes').",https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python
gemini,400,INVALID_ARGUMENT,400,false,Fix the request; check API version (v1 vs v1beta) and model support for the feature; do not retry unchanged.,"Malformed request body, unknown field, invalid parameter value (e.g. thinking_level together with thinking_budget -> 400; temperature out of [0,maxTemperature]; invalid API key -> 'API key not valid. Please pass a valid API key.'). google.rpc.Status shape: {error:{code:400,message,status:'INVALID_ARGUMENT',details:[...]}}. OpenAI-compat layer without Authorization header -> 400 INVALID_ARGUMENT 'Missing or invalid Authorization header.' (array-wrapped body).",https://ai.google.dev/gemini-api/docs/troubleshooting
gemini,400,FAILED_PRECONDITION,400,false,Enable billing in AI Studio / check available-regions; for EEA/UK/CH end users use Paid Services.,"Prerequisite not met: billing not enabled for a paid-only feature/model, or the Free tier is not available in the user's country/region ('User location is not supported for the API use'). Interactions API code: failed_precondition.",https://ai.google.dev/gemini-api/docs/api-errors
gemini,401,UNAUTHENTICATED,401,false,Verify the key/token; regenerate blocked or leaked keys in AI Studio.,Missing/invalid/expired credential (OAuth token or ephemeral token). Interactions API code: authentication. Plain invalid API keys usually surface as 400 INVALID_ARGUMENT 'API key not valid' or 403 PERMISSION_DENIED rather than 401.,https://ai.google.dev/gemini-api/docs/api-errors
gemini,403,PERMISSION_DENIED,403,false,"Check key restrictions (Restrict to Gemini API only), project, IAM; rotate leaked keys.","Key lacks permission (API not enabled on the project, key restricted to other APIs, leaked/blocked key: 'Your API key was reported as leaked. Please use another API key.', tuned model / corpus not owned by the caller). Interactions API code: permission_denied.",https://ai.google.dev/gemini-api/docs/troubleshooting
gemini,404,NOT_FOUND,404,false,Check the id against GET /v1beta/models; for 2.5 models on new keys migrate to 3.x; for previews use /v1beta.,"Model or resource not found for the API version, OR (undocumented) model no longer available to new users. Live messages: 'Model is not found: models/imagen-4.0-generate-001 for api version v1beta'; 'Model is not found: models/gemini-3.1-pro-preview for api version v1' (preview ids are v1beta-only); 'This model models/gemini-2.5-flash-lite is no longer available to new users. Please update your code to use models/gemini-3.5-flash-lite for the latest features and improvements. We recommend you to use the Interactions API.' (GET models/gemini-2.5-flash-lite still 200). OpenAI-compat with wrong auth header: 'Requested entity was not found.' Interactions codes: not_found, model_not_found.",https://ai.google.dev/gemini-api/docs/api-errors
gemini,409,ALREADY_EXISTS / ABORTED,409,aborted: yes at application level; already_exists: no,Check existence before create; retry aborted operations.,"Resource already exists (file search store / document names) or concurrency conflict. Interactions API codes: already_exists, aborted.",https://ai.google.dev/gemini-api/docs/api-errors
gemini,416,OUT_OF_RANGE,416,false,Check parameter values and limits.,Request parameter outside the valid range (Interactions API code out_of_range).,https://ai.google.dev/gemini-api/docs/api-errors
gemini,429,RESOURCE_EXHAUSTED,429,true,Back off; reduce request rate or context size; upgrade tier / request increase; for 'limit: 0' enable billing.,"RPM/TPM/RPD/IPM quota, spend-based 10-minute limit, or Flex capacity shed. Body carries google.rpc.Help + google.rpc.QuotaFailure details with quotaMetric / quotaId / quotaDimensions{model,location} and the retry delay in the message ('Please retry in 54.22s'). Free-tier keys get 'limit: 0' for paid-only models (Pro). Interactions codes: rate_limit_exceeded, quota_exceeded, too_many_requests.",https://ai.google.dev/gemini-api/docs/rate-limits
gemini,499,CANCELLED,499,n/a,No action; usually a client disconnect.,Client closed the request before completion (Interactions API code cancelled).,https://ai.google.dev/gemini-api/docs/api-errors
gemini,500,INTERNAL,500,true,Retry; reduce input; try another model.,Unexpected server error; may also surface for oversized contexts or unusual inputs. Interactions code api_error.,https://ai.google.dev/gemini-api/docs/troubleshooting
gemini,501,UNIMPLEMENTED,501,false,Check capabilities; switch to a supported feature or API version.,Operation/feature not implemented or not supported for this model/version (Interactions code unimplemented).,https://ai.google.dev/gemini-api/docs/api-errors
gemini,503,UNAVAILABLE,503,true,Retry with backoff; temporarily switch model.,Service temporarily overloaded or down ('The model is overloaded. Please try again later.'). Interactions code service_unavailable. Also used when Flex capacity is unavailable.,https://ai.google.dev/gemini-api/docs/troubleshooting
gemini,504,DEADLINE_EXCEEDED,504,true,Raise the client deadline or use background=true / Batch API.,"Request did not finish within the deadline (large prompts, long thinking, Flex queueing). Interactions code deadline_exceeded.",https://ai.google.dev/gemini-api/docs/api-errors
gemini,200,promptFeedback.blockReason,SAFETY | OTHER | BLOCKLIST | PROHIBITED_CONTENT | IMAGE_SAFETY,false,Rewrite the prompt; adjust safetySettings thresholds where allowed (not for prohibited content).,"HTTP 200 with NO candidates: the prompt itself was blocked. promptFeedback.blockReason enum (generate-content reference): BLOCK_REASON_UNSPECIFIED, SAFETY (inspect safetyRatings), OTHER (terms of service / unsupported), BLOCKLIST (terminology blocklist), PROHIBITED_CONTENT, IMAGE_SAFETY.",https://ai.google.dev/api/generate-content#BlockReason
gemini,200,candidates[].finishReason,STOP | MAX_TOKENS | SAFETY | RECITATION | LANGUAGE | OTHER | BLOCKLIST | PROHIBITED_CONTENT | SPII | MALFORMED_FUNCTION_CALL | IMAGE_SAFETY | IMAGE_PROHIBITED_CONTENT | IMAGE_OTHER | NO_IMAGE | IMAGE_RECITATION | UNEXPECTED_TOOL_CALL | TOO_MANY_TOOL_CALLS | MISSING_THOUGHT_SIGNATURE | MALFORMED_RESPONSE,MAX_TOKENS: raise maxOutputTokens / lower thinking_level; RECITATION/OTHER: change prompt; MISSING_THOUGHT_SIGNATURE: fix history,Always check finishReason before reading parts; treat non-STOP as partial.,"Why generation stopped. Live: MAX_TOKENS with maxOutputTokens=8 on thinking models (all budget spent on thoughts -> empty text, thoughtsTokenCount=5); STOP on gemini-3.5-flash-lite. RECITATION = output resembles training data (make prompt unique / raise temperature); LANGUAGE = unsupported language; MISSING_THOUGHT_SIGNATURE = Gemini 3 multi-turn function calling without echoing thoughtSignature parts. Interactions API maps these to snake_case generation codes (safety, recitation, malformed_function_call, missing_thought_signature ...).",https://ai.google.dev/api/generate-content#FinishReason
gemini,200,Interactions API error object,invalid_request | failed_precondition | out_of_range | parameter_unknown | authentication | permission_denied | not_found | model_not_found | already_exists | aborted | rate_limit_exceeded | quota_exceeded | too_many_requests | cancelled | api_error | unimplemented | service_unavailable | deadline_exceeded | <snake_case http status>,per code (rate_limit_exceeded/too_many_requests/api_error/service_unavailable/deadline_exceeded/aborted retryable),Branch on `error.code`; HTTP status still set on non-streaming responses.,"The Interactions API (/v1beta/interactions, /v1/interactions) returns {error:{code:'<snake_case>',message}} instead of google.rpc.Status; in SSE streams errors arrive as an event with event_type 'error'. Generation-blocked codes: safety, recitation, language, prohibited_content, spii, blocklist, image_safety, image_prohibited_content, image_recitation, image_other, content_blocked. Generation error codes: malformed_function_call, malformed_tool_call, unexpected_tool_call, no_image, too_many_tool_calls, missing_thought_signature.",https://ai.google.dev/gemini-api/docs/api-errors
gemini,400,OpenAI-compat error envelope,400 | 404 | 429 | 500,false,Use Authorization: Bearer <GEMINI_API_KEY>; unwrap arrays before parsing.,"The /v1beta/openai/* layer returns Google-style errors, sometimes wrapped in a JSON array: [{error:{code:400,message:'Missing or invalid Authorization header.',status:'INVALID_ARGUMENT'}}] (live). Unknown OpenAI parameters are silently ignored rather than rejected.",live probe 2026-09-19
gemini,,WebSocket close (Live API),1000-1011 + close reason,true,"Handle goAway/close, resume the session.","Live API sessions end by WebSocket close: session lifetime exceeded (15 min audio / 2 min audio+video without compression), connection reset (~10 min; use sessionResumption), goAway message before termination, invalid ephemeral token.",https://ai.google.dev/gemini-api/docs/live-api/session
openai,400,invalid_request_error,invalid_type,false,Fix the request; never retry unchanged.,"A body field has the wrong JSON type, e.g. ""Invalid type for 'max_output_tokens': expected an integer, but got a string instead."" `param` names the field.",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,missing_required_parameter,false,Add the parameter.,"""Missing required parameter: 'model'."" `param` = missing field.",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,unknown_parameter,false,Remove/rename the field; check for Chat-vs-Responses parameter differences.,"""Unknown parameter: 'x'."" The API rejects unrecognised body fields (strict schema).",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,unsupported_parameter,false,Drop the parameter for that model.,"Parameter exists but is not supported for this model/endpoint combination (e.g. `temperature` on reasoning models, `dimensions` on ada-002).",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,invalid_value,false,Correct the value; read `param` + message.,"Value out of range or not allowed, e.g. ""max_tokens is too large: 100000000. This model supports at most 32768 completion tokens"" (param=max_tokens), invalid enum member, bad model for the endpoint.",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,integer_below_min_value,false,Clamp the value.,"Integer below the allowed minimum (also `integer_above_max_value`, `string_above_max_length`, `array_above_max_length` family).",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,mutually_exclusive_parameters,false,Send only one of them.,Two body parameters cannot be combined (e.g. `previous_response_id` + `conversation`).,https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,invalid_json,false,"Fix serialisation (trailing commas, quotes).","""Invalid body: failed to parse JSON value..."" Body is not valid JSON.",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,unsupported_content_type,false,Send Content-Type: application/json (multipart/form-data only for file endpoints).,"""Unsupported content type: 'text/plain'. This API method only accepts 'application/json' requests"".",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,,false,Choose an allowed tier or change project settings.,"""Invalid service_tier argument: The requested service tier is not allowed for this project."" (`param` = service_tier). Applies to default/flex/priority (fast counts as priority); auto/omitted can also resolve to a disallowed tier.",https://developers.openai.com/api/docs/guides/error-codes#400---invalid-service_tier-argument
openai,400,invalid_request_error,invalid_beta,false,Add the documented OpenAI-Beta header.,"Endpoint requires an `OpenAI-Beta` header value that was missing/invalid (e.g. `agents=v1`, `assistants=v2`).",https://developers.openai.com/api/reference/resources/beta
openai,400,invalid_request_error,previous_response_not_found,false,Retry with full input context and `previous_response_id: null`.,"`previous_response_id` cannot be resolved (deleted, unstored `store=false`, wrong project, or WebSocket-mode state lost).",https://developers.openai.com/api/docs/guides/error-codes#websocket-mode-errors
openai,400,invalid_request_error,websocket_connection_limit_reached,true,Open a new WebSocket connection and continue.,Responses WebSocket mode connection hit the 60-minute limit.,https://developers.openai.com/api/docs/guides/error-codes#websocket-mode-errors
openai,400,invalid_request_error,context_length_exceeded,false,"Truncate/summarise input, lower max output tokens, or use Responses `truncation: ""auto""`.","Prompt + requested output exceed the model context window (""This model's maximum context length is N tokens..."").",https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,invalid_prompt,false,Change the prompt; do not retry unchanged.,Prompt rejected (e.g. flagged by safety system / unsupported content) before generation.,https://developers.openai.com/api/docs/guides/moderation
openai,400,image_generation_user_error,moderation_blocked,false,Do not auto-retry; change prompt/input.,"Image prompt/input blocked by moderation; optional `error.moderation_details {moderation_stage: input|output, categories[]}`.",https://developers.openai.com/api/docs/guides/image-generation
openai,400,invalid_request_error,content_policy_violation,false,Change the content.,Request violates usage policies (legacy images/moderation wording; current image endpoints use `moderation_blocked`).,https://developers.openai.com/api/docs/guides/error-codes
openai,400,invalid_request_error,invalid_image / invalid_image_format / image_parse_error,false,"Re-encode (PNG/JPEG/WEBP/GIF), respect size limits.","Image input cannot be decoded, wrong format, or too large.",https://developers.openai.com/api/docs/guides/images-vision
openai,400,invalid_request_error,response_already_completed,false,Re-send the injected input in the next turn.,Responses multi-agent `response.inject` failed because the target response already completed (delivered as stream event `response.inject.failed`).,https://developers.openai.com/api/docs/guides/responses-multi-agent
openai,401,invalid_request_error,invalid_api_key,false,Fix/rotate the key; SDKs raise AuthenticationError.,"""Incorrect API key provided: sk-inv***. You can find your API key at https://platform.openai.com/account/api-keys."" Note: type is `invalid_request_error` (NOT `authentication_error`).",https://developers.openai.com/api/docs/guides/error-codes#401---incorrect-api-key-provided
openai,401,invalid_request_error,,false,Get invited to an organization or use a valid key.,"""You must be a member of an organization to use the API"" / revoked key / key from another org.",https://developers.openai.com/api/docs/guides/error-codes#401---you-must-be-a-member-of-an-organization-to-use-the-api
openai,401,invalid_request_error,mismatched_organization,false,Remove the header or use the key's organization id.,"""OpenAI-Organization header should match organization for API key"".",https://developers.openai.com/api/reference/overview#authentication
openai,401,invalid_request_error,invalid_project,false,Fix the OpenAI-Project header (only meaningful with legacy user keys).,"""No such project: 'proj_...'"" when OpenAI-Project does not exist / does not belong to the key.",https://developers.openai.com/api/reference/overview#authentication
openai,401,invalid_request_error,ip_not_authorized,false,Send from an allowed IP or update the allowlist.,Request IP is outside the active IP allowlist of the project/org.,https://developers.openai.com/api/docs/guides/ip-allowlist
openai,403,,,false,Use POST https://mtls.auth.openai.com/oauth/token.,mtls.auth.openai.com: any method/path other than exact POST /oauth/token.,https://developers.openai.com/api/reference/workload-identity-federation
openai,403,invalid_request_error,insufficient_permissions,false,Use a key with the required scope.,"Structured variant of the scope error: {""error"": {""message"": ""... Missing scopes: api.external_storage.read ..."", ""type"": ""invalid_request_error"", ""code"": ""insufficient_permissions""}}.",https://developers.openai.com/api/reference/administration/overview
openai,403,invalid_request_error,misalignment_policy_violation,false,Stop the workflow; do not auto-retry; surface to an operator.,"Misalignment monitoring blocked the request before streaming; Error object may carry `misalignment{classification, message, continuation_instruction}`.",https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring
openai,403,invalid_request_error,cyber_policy,false,Do not retry; see appeals in the cybersecurity guide.,Cybersecurity safeguard classified the request as suspicious (ZDR orgs); may arrive mid-stream as an error event.,https://developers.openai.com/api/docs/guides/safety-checks/cybersecurity
openai,403,invalid_request_error,unsupported_country_region_territory,false,See the supported countries page.,"""Country, region, or territory not supported"".",https://developers.openai.com/api/docs/guides/error-codes#api-errors
openai,404,invalid_request_error,model_not_found,false,Check GET /v1/models; check project model_permissions; a 404 does not prove the model does not exist.,"""The model `x` does not exist or you do not have access to it."" Also returned for models denied by project model permissions or not yet enabled for the org (e.g. computer_use_preview).",https://developers.openai.com/api/docs/guides/error-codes
openai,404,invalid_request_error,,false,Verify the id and project; `store=false` responses are never retrievable.,"""Response with id 'resp_...' not found."" Resource lookups (responses, conversations, files, evals, fine-tuning jobs) — `code` is often null but some resources return `not_found_error` / `fine_tune_not_found` / `safety_alert_not_found` / `call_id_not_found`.",https://developers.openai.com/api/docs/guides/error-codes
openai,404,not_found_error,not_found_error,false,Verify the id.,"Stainless-style typed 404 used by newer resources (vaults, skills, chatkit, agents sessions, videos).",https://developers.openai.com/api/docs/guides/error-codes
openai,404,,,false,Check the path and API version prefix /v1.,"Unknown URL: EMPTY body (Cloudflare edge), no `x-request-id`/`openai-*` headers. E.g. GET /v1/this_endpoint_does_not_exist. Legacy Assistants/Threads routes also 404 (retired).",https://developers.openai.com/api/reference/overview
openai,405,invalid_request_error,,false,"Use the documented method (OpenAI uses POST for updates, never PATCH/PUT).","""Invalid method for URL (PATCH /v1/models)"".",https://developers.openai.com/api/reference/overview
openai,409,invalid_request_error,,true,Re-read the resource and retry once.,Conflict: resource modified concurrently / state conflict (SDK ConflictError). Example codes seen: `upload_not_pending` (400 in practice).,https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types
openai,422,invalid_request_error,,true,Docs say 'try the request again'; validate content first.,Unprocessable entity: well-formed but cannot be processed (SDK UnprocessableEntityError).,https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types
openai,429,rate_limit_error,rate_limit_exceeded,true,"Wait >= Retry-After (else exponential backoff + jitter, bounded attempts). SDKs auto-retry 2x by default. Failed requests still count.","""Rate limit reached for <model> in organization <org> on requests|tokens per min (RPM|TPM): Limit N, Used M, Requested K. Please try again in Xs."" `Retry-After` may be present.",https://developers.openai.com/api/docs/guides/rate-limits
openai,429,rate_limit_error,slow_down,true,"Follow Retry-After, reduce rate, ramp gradually.",Traffic ramped too fast (can happen under RPM/TPM). Rule of thumb: above 1M TPM grow <= 50% per 15 min.,https://developers.openai.com/api/docs/guides/error-codes#429---slow-down
openai,429,insufficient_quota,insufficient_quota,false,Add credits / raise limits; inspect `error.code` for the specific cause.,"""You exceeded your current quota, please check your plan and billing details."" Billing/quota exhaustion; retrying never helps.",https://developers.openai.com/api/docs/guides/error-codes
openai,429,insufficient_quota,credit_balance_exhausted,false,Add credits.,Prepaid credit balance depleted.,https://developers.openai.com/api/docs/guides/error-codes#429---credit-balance-exhausted
openai,429,insufficient_quota,organization_spend_limit_exceeded,false,Raise/remove the org limit or wait for monthly reset.,Organization monthly hard spend limit reached (configured via POST /v1/organization/spend_limit).,https://developers.openai.com/api/docs/guides/spend-limits
openai,429,insufficient_quota,project_spend_limit_exceeded,false,Raise/remove the project limit.,Project monthly hard spend limit reached.,https://developers.openai.com/api/docs/guides/spend-limits
openai,429,insufficient_quota,organization_usage_limit_exceeded,false,Request a higher approved usage limit / contact support.,OpenAI-assigned monthly usage limit (usage tier) reached; distinct from self-configured spend limits.,https://developers.openai.com/api/docs/guides/error-codes#429---organization-usage-limit-reached
openai,429,insufficient_quota,billing_hard_limit_reached,false,Treat like *_spend_limit_exceeded.,Legacy name of the hard-limit error (pre spend-limits API).,https://developers.openai.com/api/docs/guides/error-codes
openai,500,server_error,,true,Retry with backoff; check status.openai.com; log x-request-id.,"""The server had an error while processing your request. Sorry about that!"" Transient server fault.",https://developers.openai.com/api/docs/guides/error-codes
openai,503,service_unavailable_error,server_is_overloaded,true,"Follow Retry-After, then retry with increasing delay. Python SDK raises InternalServerError (not RateLimitError) for 503.","""The engine is currently overloaded"" — model temporarily lacks capacity. Formerly some endpoints returned 503 slow_down / 429 rate_limit_exceeded for this.",https://developers.openai.com/api/docs/guides/error-codes#503---model-temporarily-overloaded
openai,200,stream,error (SSE event),depends on code (server_error/rate_limit_exceeded yes; do not replay after output was consumed),Handle stream errors explicitly; do not auto-replay a request whose output was already consumed.,"Responses streaming: after HTTP 200 an `error` event {type:'error', code, message, param, sequence_number} or a `response.failed` event with `response.error {code, message}` may occur (codes: server_error, rate_limit_exceeded, invalid_prompt, vector_store_timeout, invalid_image, invalid_image_format, invalid_base64_image, invalid_image_url, image_too_large, image_too_small, image_parse_error, image_content_policy_violation, invalid_image_mode, image_file_too_large, unsupported_image_media_type, empty_image_file, failed_to_download_image, image_file_not_found).",https://developers.openai.com/api/reference/resources/responses/streaming-events
openai,200,response.status=incomplete,incomplete_details.reason,false,Raise max_output_tokens / continue the conversation; content_filter -> change input.,"Responses object with status `incomplete`: reasons `max_output_tokens`, `max_messages`, `content_filter`, `steered` (WebSocket response.steer). Chat Completions equivalent: finish_reason `length` / `content_filter`.",https://developers.openai.com/api/reference/resources/responses
openai,400,oauth,invalid_grant | invalid_subject_token | invalid_request,false,Decode the JWT locally and compare iss/aud/sub/exp/iat with the provider config.,"Workload identity token exchange failures at auth.openai.com / mtls.auth.openai.com: invalid_subject_token (JWT/certificate verification), invalid_grant (attribute conditions, mapping/provider config), missing/unsupported parameters.",https://developers.openai.com/api/reference/workload-identity-federation#token-exchange-errors
openai,,sdk,APIConnectionError | APITimeoutError,true,Retry with backoff; check network; raise timeout for long generations or use background mode.,Client-side: network/proxy/SSL failure or request exceeded the SDK timeout (default 600 s Python / 10 min Node).,https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types
xai,400,invalid-argument,invalid-argument,false,"Fix the request; check the model page for supported parameters (e.g. reasoning_effort only on grok-4.6/4.5/4.3, multi-agent only on /v1/responses).","Bad request body/URL, unsupported parameter for the model, or an incorrect API key (xAI returns 400 not 401 for a malformed/unknown key). Body shape: {""code"": ""invalid-argument"", ""error"": ""<message>""}. Some 400s are a bare JSON string (multi-agent on chat completions).",https://docs.x.ai/developers/debugging
xai,401,unauthenticated,unauthenticated:no-credentials,false,Send Authorization: Bearer <XAI_API_KEY>; use a Management key on management-api.x.ai.,"No Authorization header. Note: an INVALID key yields 400 invalid-argument on the inference API, while the Management API returns 401 with a gRPC-style body {""code"": 16, ""message"": ""Invalid bearer token. Please ensure you use a valid management key."", ""details"": []} (16 = UNAUTHENTICATED).",https://docs.x.ai/developers/debugging
xai,403,forbidden,permission-denied (assumed),false,"Check GET /v1/api-key (acls, api_key_blocked, api_key_disabled, team_blocked); have an admin fix ACLs via console or Management API.","Key lacks an ACL (api-key:endpoint:<name> / api-key:model:<name>), key disabled/blocked, team blocked, or ZDR/feature restriction. Docs: 'Ask your team admin for permission.'",https://docs.x.ai/developers/debugging
xai,404,not-found,not-found,false,Check the id against GET /v1/models on the SAME base URL; contact support with team id + model name if access is expected.,"Unknown path, or model 'does not exist or your team <team_id> does not have access to it' (the same message covers non-existent and restricted models -> never conclude non-existence). Regional endpoints return 404 for models they do not serve (e.g. grok-latest on us.api.x.ai).",https://docs.x.ai/developers/debugging
xai,405,method-not-allowed,,false,Check the method in the REST reference.,HTTP method not supported by the path (e.g. POST to a GET-only endpoint). Empty body observed.,https://docs.x.ai/developers/debugging
xai,415,unsupported-media-type,,false,Send application/json (or multipart/form-data where required).,Wrong Content-Type on a POST endpoint.,https://docs.x.ai/developers/debugging
xai,422,unprocessable-entity,,false,"Fix field types (message names the field, line and column).","A field of the POST body has an invalid format/type. Body is a plain JSON string from the deserializer (serde-style), not the {code,error} object.",https://docs.x.ai/developers/debugging
xai,429,too-many-requests,resource-exhausted (gRPC RESOURCE_EXHAUSTED),true,Back off; spread load; raise tier via spend or console request; move bulk work to the Batch API (does not count towards rate limits).,"Per-model RPS or TPM limit of the team exceeded, or per-key qps/qpm/tpm cap set via the Management API, or prepaid credits depleted with a $0 invoiced-billing limit (requests 'automatically rejected' - status code for this case not documented).",https://docs.x.ai/developers/rate-limits
xai,500,internal,,true,Retry; report persistent failures to support@x.ai with x-request-id.,Server-side failure (not enumerated in docs; check https://status.x.ai and the RSS feed https://status.x.ai/feed.xml).,https://docs.x.ai/developers/debugging
xai,202,accepted (not an error),,true,Poll with backoff.,GET /v1/chat/deferred-completion/{request_id}: result not ready yet (empty body). Deferred results can be fetched exactly once within 24 h.,https://docs.x.ai/developers/advanced-api-usage/deferred-chat-completions
xai,200,"usage-guideline-violation (billing event, not an HTTP error)",,false,Review content policy.,Requests judged to violate usage guidelines are still charged; violations caught before generation on the Responses API incur a flat $0.05 fee.,https://docs.x.ai/developers/pricing
xai,,grpc-status-mapping,gRPC codes,,"In xai-sdk, catch grpc.RpcError and inspect e.code().","gRPC API (api.x.ai:443, xai_api.* services) surfaces canonical gRPC status codes; the Management API's REST error body {code, message, details} uses the same numbering. Mapping used by the SDK/docs: 3 INVALID_ARGUMENT -> 400; 16 UNAUTHENTICATED -> 401; 7 PERMISSION_DENIED -> 403; 5 NOT_FOUND -> 404; 8 RESOURCE_EXHAUSTED -> 429 (rate limit; xai-sdk docs catch grpc.StatusCode.RESOURCE_EXHAUSTED); 13 INTERNAL -> 500; 14 UNAVAILABLE -> 503; 4 DEADLINE_EXCEEDED -> 504 (SDK default timeout 1620 s).",https://docs.x.ai/developers/rate-limits