[ { "provider": "anthropic", "api_family": "compliance", "http_status": 400, "type": "invalid_request_error", "code": "compliance_api_not_enabled", "message_semantics": "`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.", "retryable": false, "recommended_action": "Enable the Compliance API (claude.ai > Organization settings > API for Enterprise; Console > Settings > Security toggle for standalone Console org), then resend.", "backoff": null, "category": "invalid_request", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 400, "type": "invalid_request_error", "code": "unknown_query_parameter", "message_semantics": "`Unknown query parameter: 'created_at[gte]'. Did you mean 'created_at.gte'?` — unrecognized params are rejected, not ignored.", "retryable": false, "recommended_action": "Use dot notation for ranges (created_at.gte), `[]` suffix for arrays (activity_types[]), and after_id/before_id/page per endpoint.", "backoff": null, "category": "invalid_request", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 400, "type": "invalid_request_error", "code": "invalid_parameter_value", "message_semantics": "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.", "retryable": false, "recommended_action": "Correct the named parameter; respect per-endpoint limit maxima; RFC 3339 timestamps with explicit UTC offset.", "backoff": null, "category": "invalid_request", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 400, "type": "invalid_request_error", "code": "invalid_pagination_cursor", "message_semantics": "`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).", "retryable": false, "recommended_action": "Treat cursors as opaque; copy first_id/last_id/next_page unchanged; on expiry restart without page.", "backoff": null, "category": "invalid_request", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 401, "type": "authentication_error", "code": "api_key_invalid", "message_semantics": "`API key is invalid.` — value does not match a usable Compliance Access Key / Admin API key (truncated/altered).", "retryable": false, "recommended_action": "Compare stored secret; create a new key if the copy is wrong.", "backoff": null, "category": "authentication", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 401, "type": "authentication_error", "code": "api_key_deactivated", "message_semantics": "`API key has been deactivated.` — key disabled or deleted.", "retryable": false, "recommended_action": "Re-enable if only disabled; otherwise create a new key and rotate.", "backoff": null, "category": "authentication", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 401, "type": "authentication_error", "code": "api_key_expired", "message_semantics": "`API key has expired.` — Admin API key past its expiration (Compliance Access Keys have no expiry).", "retryable": false, "recommended_action": "Create a new key and update the integration.", "backoff": null, "category": "authentication", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 403, "type": "permission_error", "code": "insufficient_scope_activities", "message_semantics": "`Missing required scopes. Got: [...] Needed one of: ['read:compliance_activities', 'read:org_audit']` on GET /v1/compliance/activities.", "retryable": false, "recommended_action": "Create a Compliance Access Key with read:compliance_activities, or use an Admin API key created while the Compliance API was enabled.", "backoff": null, "category": "permission", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 403, "type": "permission_error", "code": "insufficient_scope_org_data", "message_semantics": "`… Needed one of: ['read:compliance_org_data', 'read:org_audit']` on organizations/roles/groups/settings endpoints; Admin API keys cannot read org metadata.", "retryable": false, "recommended_action": "Create a new Compliance Access Key with read:compliance_org_data.", "backoff": null, "category": "permission", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 403, "type": "permission_error", "code": "retired_scope_org_settings", "message_semantics": "`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.", "retryable": false, "recommended_action": "Create a new key with read:compliance_org_data, migrate, delete the old key.", "backoff": null, "category": "permission", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 403, "type": "permission_error", "code": "insufficient_scope_user_data", "message_semantics": "`… 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.", "retryable": false, "recommended_action": "Use a Compliance Access Key created in claude.ai with read:compliance_user_data.", "backoff": null, "category": "permission", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 403, "type": "permission_error", "code": "insufficient_scope_delete", "message_semantics": "`… Needed: ['delete:compliance_user_data']` on DELETE chats/files/projects/documents.", "retryable": false, "recommended_action": "Create a separate key carrying delete:compliance_user_data (keep read and delete keys separate).", "backoff": null, "category": "permission", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "request_not_authenticated", "message_semantics": "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.", "retryable": false, "recommended_action": "Send an sk-ant-api01- or sk-ant-admin01- key in x-api-key; check the path against the reference.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "chat_not_found", "message_semantics": "`Chat conversation not found: ''` — hard-deleted, retention-expired, or outside key scope. User-deleted chats are NOT 404 (listed with deleted_at).", "retryable": false, "recommended_action": "Reconcile against claude_chat_created / claude_chat_viewed activities; drop the ID from the queue.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "file_not_found", "message_semantics": "`File not found: ` — 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.", "retryable": false, "recommended_action": "Reconcile against claude_file_uploaded / claude_file_deleted / claude_chat_deleted activities.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "generated_file_or_artifact_not_found", "message_semantics": "`Generated file not found: '…'` (metadata) / `Generated file content not found: '…'` (content) / `Artifact version not found: '…'` (both artifact endpoints) — deleted with their chat.", "retryable": false, "recommended_action": "Look up the chat via Get chat messages; if deleted_at set, remove from queue.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "project_not_found", "message_semantics": "`No project is found with the provided id.` (detail/attachments/collaborators) / `No project found with provided id, or it has already been deleted.` (DELETE).", "retryable": false, "recommended_action": "Reconcile against claude_project_created / claude_project_deleted activities.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "project_document_not_found", "message_semantics": "`No project document found with the provided id.` / `…, or it has already been deleted.` (DELETE) — text project documents (claude_proj_doc_) only.", "retryable": false, "recommended_action": "List current attachments via GET /v1/compliance/apps/projects/{project_id}/attachments.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "local_session_not_found", "message_semantics": "`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.", "retryable": false, "recommended_action": "Confirm via the local session list; if absent, transcript is not retrievable.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "local_sessions_not_available", "message_semantics": "`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.", "retryable": true, "recommended_action": "Keep queued IDs; retry on the next scheduled run; if persistent contact Anthropic with request-id.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "remote_session_not_found", "message_semantics": "`Remote session not found.` — `cse_` ID missing/deleted, outside scope, or session still `pending` (no transcript yet). Malformed ID → 400.", "retryable": "conditional", "recommended_action": "Check status via the remote session list; retry after it leaves pending; deleted sessions are gone.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "organization_role_or_group_not_found", "message_semantics": "`The \"\" organization does not exist or the requester is not authorized to access it.` / `Role not found.` / `Group not found.`", "retryable": false, "recommended_action": "Verify the ID against the corresponding list endpoint.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 404, "type": "not_found_error", "code": "organization_settings_not_available", "message_semantics": "`organization `` 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).", "retryable": false, "recommended_action": "Verify against List organizations; if a known-good ID still 404s, contact your Anthropic representative.", "backoff": null, "category": "not_found", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 409, "type": "invalid_request_error", "code": "project_has_attached_chats", "message_semantics": "`The \"\" 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).", "retryable": false, "recommended_action": "List chats with user_ids[] + project_ids[], delete or detach each, retry the project delete.", "backoff": null, "category": "invalid_request", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 429, "type": "rate_limit_error", "code": "compliance_rate_limit_exceeded", "message_semantics": "`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).", "retryable": true, "recommended_action": "Wait `retry-after` seconds (fallback exponential backoff 1 s → 60 s); do NOT advance the cursor. Headers: anthropic-ratelimit-requests-limit/-remaining/-reset.", "backoff": "retry-after header; else exponential 1s doubling to 60s", "category": "rate_limit", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "http_status": 500, "type": "api_error", "code": null, "message_semantics": "Unexpected internal error.", "retryable": true, "recommended_action": "Retry with exponential backoff; if persistent, contact support with request_id.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": "502/503/504/529", "type": null, "code": null, "message_semantics": "Transient upstream/overload errors.", "retryable": true, "recommended_action": "Retry with exponential backoff; check status.anthropic.com. Exception: some local-session 503s are not transient (see overloaded_error).", "backoff": "exponential 1s→60s", "category": "capacity", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 503, "type": "overloaded_error", "code": "local_sessions_index_unavailable", "message_semantics": "`The local-sessions index is temporarily unavailable. Try again shortly.` — transient.", "retryable": true, "recommended_action": "Retry with backoff; do not advance page cursor.", "backoff": "exponential", "category": "overload", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 503, "type": "overloaded_error", "code": "local_sessions_captured_content_unavailable", "message_semantics": "`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).", "retryable": "conditional", "recommended_action": "Retry with backoff; if it keeps recurring for a CMEK org, check the key in your KMS and stop walking that org's transcripts.", "backoff": "exponential", "category": "overload", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "api_family": "compliance", "http_status": 503, "type": "overloaded_error", "code": "local_sessions_retention_overrides_unavailable", "message_semantics": "`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.", "retryable": "conditional", "recommended_action": "Do not hold the walk open: narrow created_at window or skip the session and retry on a later run (restart without page).", "backoff": "retry on a later run", "category": "overload", "observed_live": false, "example": null, "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors", "_fragment": "generated/fragments/errors/anthropic-compliance.json" }, { "provider": "anthropic", "http_status": 400, "type": "invalid_request_error", "code": null, "message_semantics": "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.", "retryable": false, "recommended_action": "Fix the request (message names the field, e.g. 'max_tokens: Field required'). Do not retry unchanged.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://platform.claude.com/docs/en/api/errors", "live_messages": [ "max_tokens: Field required", "max_tokens: 1000000 > 64000, which is the maximum allowed number of output tokens for claude-haiku-4-5-20251001", "temperature: range: 0..1", "top_k: Input should be a valid integer", "`temperature` and `top_p` cannot both be specified for this model. Please use only one.", "messages: at least one message is required", "The request body is not valid JSON: …", "anthropic-version: \"2020-01-01\" is not a valid version", "anthropic-version: \"2023-01-01\" not allowed for this endpoint", "Unexpected value(s) `…` for the `anthropic-beta` header. …", "This model does not support assistant message prefill. The conversation must end with a user message.", "adaptive thinking is not supported on this model", "messages.2: `tool_use` ids were found without `tool_result` blocks immediately after: … Each `tool_use` block must have a corresponding `tool_result` block in the next message.", "Server tools are not supported in the count_tokens endpoint: web_search_20250305. Use the /v1/messages endpoint instead.", "'claude-haiku-4-5-20251001' does not support inference_geo.", "'claude-haiku-4-5-20251001' does not support the `speed` parameter. This feature is only available on supported models.", "betas: Extra inputs are not permitted", "output_format: Extra inputs are not permitted", "The /v1/complete endpoint has been deprecated. Please use the /v1/messages endpoint instead. See https://platform.claude.com/docs/en/api/messages for details." ], "response_headers": { "x-should-retry": "false" }, "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 401, "type": "authentication_error", "code": null, "message_semantics": "API key malformed, revoked, expired (or bad AWS SigV4 on Claude Platform on AWS).", "retryable": false, "recommended_action": "Check the key / auth header. Live: 'invalid x-api-key'; anthropic-organization-id header absent on 401.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 402, "type": "billing_error", "code": null, "message_semantics": "Billing/payment problem.", "retryable": false, "recommended_action": "Fix payment details in Console (or AWS Marketplace).", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 403, "type": "permission_error", "code": null, "message_semantics": "Key lacks permission for the resource (workspace/org settings).", "retryable": false, "recommended_action": "Check organization access / workspace settings. Does NOT mean the endpoint doesn't exist.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 404, "type": "not_found_error", "code": null, "message_semantics": "Resource not found: unknown path, unknown resource id, or unknown model ('model: ').", "retryable": false, "recommended_action": "Check path/ids; for models, use GET /v1/models.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 409, "type": "conflict_error", "code": null, "message_semantics": "Request conflicts with resource state (concurrent modification, uniqueness).", "retryable": true, "recommended_action": "Resolve the conflict then retry (SDKs retry 409 by default).", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 413, "type": "request_too_large", "code": null, "message_semantics": "Body exceeds the size limit: Messages & count_tokens 32 MB, Batches 256 MB, Files 500 MB (returned by Cloudflare before the API).", "retryable": false, "recommended_action": "Shrink the request (use Files API / batches).", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 422, "type": "unprocessable_entity (SDK class only)", "code": null, "message_semantics": "Not in the HTTP error list of the docs; SDKs map 422 to UnprocessableEntityError.", "retryable": false, "recommended_action": "Treat like 400.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 429, "type": "rate_limit_error", "code": null, "message_semantics": "Rate limit (RPM/ITPM/OTPM), monthly tier spend cap (no retry-after header, keeps failing), acceleration limit, or Claude Code workspace spend limit.", "retryable": true, "recommended_action": "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.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "response_headers": [ "retry-after", "anthropic-ratelimit-*" ], "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 504, "type": "timeout_error", "code": null, "message_semantics": "Request timed out while processing.", "retryable": true, "recommended_action": "Use streaming or the Batches API for long requests; retry.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 529, "type": "overloaded_error", "code": null, "message_semantics": "API temporarily overloaded (all users); can also arrive as a mid-stream `error` event after HTTP 200.", "retryable": true, "recommended_action": "Retry with backoff; Priority Tier reduces occurrence. Handle the SSE `error` event.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": null, "type": "streaming error event", "code": null, "message_semantics": "After HTTP 200 the stream may emit `event: error` with {type: error, error:{type, message}} (e.g. overloaded_error).", "retryable": true, "recommended_action": "Abort the stream, then retry (SDKs raise; Claude 4.6+: resume by sending partial text in a user message asking to continue).", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/build-with-claude/streaming", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": null, "type": "x-should-retry header", "code": null, "message_semantics": "Observed on every error response: `x-should-retry: false` for 4xx; SDKs consult this header (true/false) before their status-based retry decision.", "retryable": null, "recommended_action": "Respect it when present.", "status": [ "LIVE_DISCOVERED" ], "source": "https://platform.claude.com/docs/en/api/errors", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": 200, "type": "stop_reason: refusal", "code": null, "message_semantics": "Not an error: safety classifiers stopped generation; HTTP 200 with stop_details.category.", "retryable": false, "recommended_action": "Retry on a fallback model (server-side `fallbacks` beta or client-side), redeem fallback_credit_token.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": null, "type": "tool result error codes", "code": null, "message_semantics": "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).", "retryable": null, "recommended_action": "Inspect the result block; `too_many_requests`/`unavailable` are transient.", "status": [ "DOCUMENTED" ], "source": "https://platform.claude.com/docs/en/api/messages", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "anthropic", "http_status": null, "type": "SDK retry policy", "code": null, "message_semantics": "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').", "retryable": null, "recommended_action": "Configure max_retries / timeout; stream for large max_tokens.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python", "verification_note": "constants read from installed anthropic 1.7.0 and @anthropic-ai/sdk 0.126.0", "_fragment": "generated/fragments/errors/anthropic-errors.json" }, { "provider": "gemini", "http_status": 400, "type": "INVALID_ARGUMENT", "code": "400", "category": "invalid_request", "message_semantics": "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).", "retryable": false, "recommended_action": "Fix the request; check API version (v1 vs v1beta) and model support for the feature; do not retry unchanged.", "observed_live": true, "example": [ { "error": { "code": 400, "message": "Missing or invalid Authorization header.", "status": "INVALID_ARGUMENT" } } ], "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://ai.google.dev/gemini-api/docs/troubleshooting", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 400, "type": "FAILED_PRECONDITION", "code": "400", "category": "permission", "message_semantics": "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.", "retryable": false, "recommended_action": "Enable billing in AI Studio / check available-regions; for EEA/UK/CH end users use Paid Services.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 401, "type": "UNAUTHENTICATED", "code": "401", "category": "authentication", "message_semantics": "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.", "retryable": false, "recommended_action": "Verify the key/token; regenerate blocked or leaked keys in AI Studio.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 403, "type": "PERMISSION_DENIED", "code": "403", "category": "permission", "message_semantics": "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.", "retryable": false, "recommended_action": "Check key restrictions (Restrict to Gemini API only), project, IAM; rotate leaked keys.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/troubleshooting", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 404, "type": "NOT_FOUND", "code": "404", "category": "not_found", "message_semantics": "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.", "retryable": false, "recommended_action": "Check the id against GET /v1beta/models; for 2.5 models on new keys migrate to 3.x; for previews use /v1beta.", "observed_live": true, "example": { "error": { "code": 404, "message": "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.", "status": "NOT_FOUND" } }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 409, "type": "ALREADY_EXISTS / ABORTED", "code": "409", "category": "invalid_request", "message_semantics": "Resource already exists (file search store / document names) or concurrency conflict. Interactions API codes: already_exists, aborted.", "retryable": "aborted: yes at application level; already_exists: no", "recommended_action": "Check existence before create; retry aborted operations.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 416, "type": "OUT_OF_RANGE", "code": "416", "category": "invalid_request", "message_semantics": "Request parameter outside the valid range (Interactions API code out_of_range).", "retryable": false, "recommended_action": "Check parameter values and limits.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 429, "type": "RESOURCE_EXHAUSTED", "code": "429", "category": "rate_limit", "message_semantics": "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.", "retryable": true, "backoff": "exponential with jitter (1s, 2s, 4s, 8s...), cap attempts; SDK default 4 attempts, initial ~1s, max 60s; honour the seconds in the message; no Retry-After header", "recommended_action": "Back off; reduce request rate or context size; upgrade tier / request increase; for 'limit: 0' enable billing.", "observed_live": true, "example": { "error": { "code": 429, "message": "You exceeded your current quota, please check your plan and billing details. ... * Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 0, model: gemini-3.1-pro ... Please retry in 50.868302469s.", "status": "RESOURCE_EXHAUSTED", "details": [ { "@type": "type.googleapis.com/google.rpc.Help" }, { "@type": "type.googleapis.com/google.rpc.QuotaFailure", "violations": [ { "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests", "quotaId": "GenerateRequestsPerDayPerProjectPerModel-FreeTier", "quotaDimensions": { "model": "gemini-3.1-pro", "location": "global" } } ] } ] } }, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://ai.google.dev/gemini-api/docs/rate-limits", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 499, "type": "CANCELLED", "code": "499", "category": "timeout", "message_semantics": "Client closed the request before completion (Interactions API code cancelled).", "retryable": "n/a", "recommended_action": "No action; usually a client disconnect.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 500, "type": "INTERNAL", "code": "500", "category": "server_error", "message_semantics": "Unexpected server error; may also surface for oversized contexts or unusual inputs. Interactions code api_error.", "retryable": true, "backoff": "exponential; if persistent reduce context / switch model / report on the forum", "recommended_action": "Retry; reduce input; try another model.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/troubleshooting", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 501, "type": "UNIMPLEMENTED", "code": "501", "category": "invalid_request", "message_semantics": "Operation/feature not implemented or not supported for this model/version (Interactions code unimplemented).", "retryable": false, "recommended_action": "Check capabilities; switch to a supported feature or API version.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 503, "type": "UNAVAILABLE", "code": "503", "category": "overload", "message_semantics": "Service temporarily overloaded or down ('The model is overloaded. Please try again later.'). Interactions code service_unavailable. Also used when Flex capacity is unavailable.", "retryable": true, "backoff": "exponential with jitter; consider Priority tier for business-critical traffic, or a Flash/Lite fallback model", "recommended_action": "Retry with backoff; temporarily switch model.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/troubleshooting", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 504, "type": "DEADLINE_EXCEEDED", "code": "504", "category": "timeout", "message_semantics": "Request did not finish within the deadline (large prompts, long thinking, Flex queueing). Interactions code deadline_exceeded.", "retryable": true, "backoff": "increase/remove client timeout (SDK http_options.timeout), use streaming, background execution or Batch", "recommended_action": "Raise the client deadline or use background=true / Batch API.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 200, "type": "promptFeedback.blockReason", "code": "SAFETY | OTHER | BLOCKLIST | PROHIBITED_CONTENT | IMAGE_SAFETY", "category": "content_safety", "message_semantics": "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.", "retryable": false, "recommended_action": "Rewrite the prompt; adjust safetySettings thresholds where allowed (not for prohibited content).", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/api/generate-content#BlockReason", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 200, "type": "candidates[].finishReason", "code": "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", "category": "content_safety", "message_semantics": "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 ...).", "retryable": "MAX_TOKENS: raise maxOutputTokens / lower thinking_level; RECITATION/OTHER: change prompt; MISSING_THOUGHT_SIGNATURE: fix history", "recommended_action": "Always check finishReason before reading parts; treat non-STOP as partial.", "observed_live": true, "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "source": "https://ai.google.dev/api/generate-content#FinishReason", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 200, "type": "Interactions API error object", "code": "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 | ", "category": "invalid_request", "message_semantics": "The Interactions API (/v1beta/interactions, /v1/interactions) returns {error:{code:'',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.", "retryable": "per code (rate_limit_exceeded/too_many_requests/api_error/service_unavailable/deadline_exceeded/aborted retryable)", "recommended_action": "Branch on `error.code`; HTTP status still set on non-streaming responses.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/api-errors", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": 400, "type": "OpenAI-compat error envelope", "code": "400 | 404 | 429 | 500", "category": "invalid_request", "message_semantics": "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.", "retryable": false, "recommended_action": "Use Authorization: Bearer ; unwrap arrays before parsing.", "observed_live": true, "status": [ "LIVE_VERIFIED" ], "source": "live probe 2026-09-19", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "gemini", "http_status": null, "type": "WebSocket close (Live API)", "code": "1000-1011 + close reason", "category": "timeout", "message_semantics": "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.", "retryable": true, "backoff": "reconnect with the sessionResumption handle (valid 2 h)", "recommended_action": "Handle goAway/close, resume the session.", "observed_live": false, "status": [ "DOCUMENTED" ], "source": "https://ai.google.dev/gemini-api/docs/live-api/session", "_fragment": "generated/fragments/errors/gemini-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "invalid_type", "message_semantics": "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.", "retryable": false, "recommended_action": "Fix the request; never retry unchanged.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "POST /v1/responses", "param": "max_output_tokens" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "missing_required_parameter", "message_semantics": "\"Missing required parameter: 'model'.\" `param` = missing field.", "retryable": false, "recommended_action": "Add the parameter.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "POST /v1/responses" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "unknown_parameter", "message_semantics": "\"Unknown parameter: 'x'.\" The API rejects unrecognised body fields (strict schema).", "retryable": false, "recommended_action": "Remove/rename the field; check for Chat-vs-Responses parameter differences.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "POST /v1/responses" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "unsupported_parameter", "message_semantics": "Parameter exists but is not supported for this model/endpoint combination (e.g. `temperature` on reasoning models, `dimensions` on ada-002).", "retryable": false, "recommended_action": "Drop the parameter for that model.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "note": "seen in other agents' probes (tmp-live)" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "invalid_value", "message_semantics": "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.", "retryable": false, "recommended_action": "Correct the value; read `param` + message.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "POST /v1/chat/completions", "param": "max_tokens" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "integer_below_min_value", "message_semantics": "Integer below the allowed minimum (also `integer_above_max_value`, `string_above_max_length`, `array_above_max_length` family).", "retryable": false, "recommended_action": "Clamp the value.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "note": "seen in other agents' probes" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "mutually_exclusive_parameters", "message_semantics": "Two body parameters cannot be combined (e.g. `previous_response_id` + `conversation`).", "retryable": false, "recommended_action": "Send only one of them.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "note": "seen in other agents' probes" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "invalid_json", "message_semantics": "\"Invalid body: failed to parse JSON value...\" Body is not valid JSON.", "retryable": false, "recommended_action": "Fix serialisation (trailing commas, quotes).", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "POST /v1/responses" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "unsupported_content_type", "message_semantics": "\"Unsupported content type: 'text/plain'. This API method only accepts 'application/json' requests\".", "retryable": false, "recommended_action": "Send Content-Type: application/json (multipart/form-data only for file endpoints).", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "POST /v1/responses" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": null, "message_semantics": "\"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.", "retryable": false, "recommended_action": "Choose an allowed tier or change project settings.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#400---invalid-service_tier-argument", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "invalid_beta", "message_semantics": "Endpoint requires an `OpenAI-Beta` header value that was missing/invalid (e.g. `agents=v1`, `assistants=v2`).", "retryable": false, "recommended_action": "Add the documented OpenAI-Beta header.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "note": "GET /v1/agents without OpenAI-Beta (other agent's probe)" }, "source": "https://developers.openai.com/api/reference/resources/beta", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "previous_response_not_found", "message_semantics": "`previous_response_id` cannot be resolved (deleted, unstored `store=false`, wrong project, or WebSocket-mode state lost).", "retryable": false, "recommended_action": "Retry with full input context and `previous_response_id: null`.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "note": "other agent's probe" }, "source": "https://developers.openai.com/api/docs/guides/error-codes#websocket-mode-errors", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "websocket_connection_limit_reached", "message_semantics": "Responses WebSocket mode connection hit the 60-minute limit.", "retryable": true, "recommended_action": "Open a new WebSocket connection and continue.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#websocket-mode-errors", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "context_length_exceeded", "message_semantics": "Prompt + requested output exceed the model context window (\"This model's maximum context length is N tokens...\").", "retryable": false, "recommended_action": "Truncate/summarise input, lower max output tokens, or use Responses `truncation: \"auto\"`.", "status": [ "DOCUMENTED" ], "note": "Documented historically in the error-codes guide/community; in our probe an oversized max_tokens returned code `invalid_value` instead.", "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "invalid_prompt", "message_semantics": "Prompt rejected (e.g. flagged by safety system / unsupported content) before generation.", "retryable": false, "recommended_action": "Change the prompt; do not retry unchanged.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/moderation", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "image_generation_user_error", "code": "moderation_blocked", "message_semantics": "Image prompt/input blocked by moderation; optional `error.moderation_details {moderation_stage: input|output, categories[]}`.", "retryable": false, "recommended_action": "Do not auto-retry; change prompt/input.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/image-generation", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "content_policy_violation", "message_semantics": "Request violates usage policies (legacy images/moderation wording; current image endpoints use `moderation_blocked`).", "retryable": false, "recommended_action": "Change the content.", "status": [ "DOCUMENTED", "LEGACY" ], "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "invalid_image / invalid_image_format / image_parse_error", "message_semantics": "Image input cannot be decoded, wrong format, or too large.", "retryable": false, "recommended_action": "Re-encode (PNG/JPEG/WEBP/GIF), respect size limits.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/images-vision", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "invalid_request_error", "code": "response_already_completed", "message_semantics": "Responses multi-agent `response.inject` failed because the target response already completed (delivered as stream event `response.inject.failed`).", "retryable": false, "recommended_action": "Re-send the injected input in the next turn.", "status": [ "DOCUMENTED", "BETA" ], "source": "https://developers.openai.com/api/docs/guides/responses-multi-agent", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 401, "type": "invalid_request_error", "code": "invalid_api_key", "message_semantics": "\"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`).", "retryable": false, "recommended_action": "Fix/rotate the key; SDKs raise AuthenticationError.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "GET /v1/models", "request_note": "Authorization: Bearer sk-invalid (literal)" }, "source": "https://developers.openai.com/api/docs/guides/error-codes#401---incorrect-api-key-provided", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 401, "type": "invalid_request_error", "code": null, "message_semantics": "\"You must be a member of an organization to use the API\" / revoked key / key from another org.", "retryable": false, "recommended_action": "Get invited to an organization or use a valid key.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#401---you-must-be-a-member-of-an-organization-to-use-the-api", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 401, "type": "invalid_request_error", "code": "mismatched_organization", "message_semantics": "\"OpenAI-Organization header should match organization for API key\".", "retryable": false, "recommended_action": "Remove the header or use the key's organization id.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "GET /v1/models" }, "source": "https://developers.openai.com/api/reference/overview#authentication", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 401, "type": "invalid_request_error", "code": "invalid_project", "message_semantics": "\"No such project: 'proj_...'\" when OpenAI-Project does not exist / does not belong to the key.", "retryable": false, "recommended_action": "Fix the OpenAI-Project header (only meaningful with legacy user keys).", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "GET /v1/models" }, "source": "https://developers.openai.com/api/reference/overview#authentication", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 401, "type": "invalid_request_error", "code": "ip_not_authorized", "message_semantics": "Request IP is outside the active IP allowlist of the project/org.", "retryable": false, "recommended_action": "Send from an allowed IP or update the allowlist.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/ip-allowlist", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 403, "type": null, "code": null, "message_semantics": "mtls.auth.openai.com: any method/path other than exact POST /oauth/token.", "retryable": false, "recommended_action": "Use POST https://mtls.auth.openai.com/oauth/token.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/reference/workload-identity-federation", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 403, "type": "invalid_request_error", "code": "insufficient_permissions", "message_semantics": "Structured variant of the scope error: {\"error\": {\"message\": \"... Missing scopes: api.external_storage.read ...\", \"type\": \"invalid_request_error\", \"code\": \"insufficient_permissions\"}}.", "retryable": false, "recommended_action": "Use a key with the required scope.", "status": [ "LIVE_VERIFIED", "ACCOUNT_RESTRICTED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "GET /v1/organization/external_storage" }, "source": "https://developers.openai.com/api/reference/administration/overview", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 403, "type": "invalid_request_error", "code": "misalignment_policy_violation", "message_semantics": "Misalignment monitoring blocked the request before streaming; Error object may carry `misalignment{classification, message, continuation_instruction}`.", "retryable": false, "recommended_action": "Stop the workflow; do not auto-retry; surface to an operator.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 403, "type": "invalid_request_error", "code": "cyber_policy", "message_semantics": "Cybersecurity safeguard classified the request as suspicious (ZDR orgs); may arrive mid-stream as an error event.", "retryable": false, "recommended_action": "Do not retry; see appeals in the cybersecurity guide.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/safety-checks/cybersecurity", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 403, "type": "invalid_request_error", "code": "unsupported_country_region_territory", "message_semantics": "\"Country, region, or territory not supported\".", "retryable": false, "recommended_action": "See the supported countries page.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#api-errors", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 404, "type": "invalid_request_error", "code": "model_not_found", "message_semantics": "\"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).", "retryable": false, "recommended_action": "Check GET /v1/models; check project model_permissions; a 404 does not prove the model does not exist.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "POST /v1/responses" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 404, "type": "invalid_request_error", "code": null, "message_semantics": "\"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`.", "retryable": false, "recommended_action": "Verify the id and project; `store=false` responses are never retrievable.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "GET /v1/responses/{id}" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 404, "type": "not_found_error", "code": "not_found_error", "message_semantics": "Stainless-style typed 404 used by newer resources (vaults, skills, chatkit, agents sessions, videos).", "retryable": false, "recommended_action": "Verify the id.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "note": "other agents' probes" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 404, "type": null, "code": null, "message_semantics": "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).", "retryable": false, "recommended_action": "Check the path and API version prefix /v1.", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "GET /v1/this_endpoint_does_not_exist" }, "source": "https://developers.openai.com/api/reference/overview", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 405, "type": "invalid_request_error", "code": null, "message_semantics": "\"Invalid method for URL (PATCH /v1/models)\".", "retryable": false, "recommended_action": "Use the documented method (OpenAI uses POST for updates, never PATCH/PUT).", "status": [ "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "endpoint": "PATCH /v1/models" }, "source": "https://developers.openai.com/api/reference/overview", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 409, "type": "invalid_request_error", "code": null, "message_semantics": "Conflict: resource modified concurrently / state conflict (SDK ConflictError). Example codes seen: `upload_not_pending` (400 in practice).", "retryable": true, "recommended_action": "Re-read the resource and retry once.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 422, "type": "invalid_request_error", "code": null, "message_semantics": "Unprocessable entity: well-formed but cannot be processed (SDK UnprocessableEntityError).", "retryable": true, "recommended_action": "Docs say 'try the request again'; validate content first.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "rate_limit_error", "code": "rate_limit_exceeded", "message_semantics": "\"Rate limit reached for in organization on requests|tokens per min (RPM|TPM): Limit N, Used M, Requested K. Please try again in Xs.\" `Retry-After` may be present.", "retryable": true, "recommended_action": "Wait >= Retry-After (else exponential backoff + jitter, bounded attempts). SDKs auto-retry 2x by default. Failed requests still count.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/rate-limits", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "rate_limit_error", "code": "slow_down", "message_semantics": "Traffic ramped too fast (can happen under RPM/TPM). Rule of thumb: above 1M TPM grow <= 50% per 15 min.", "retryable": true, "recommended_action": "Follow Retry-After, reduce rate, ramp gradually.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#429---slow-down", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "insufficient_quota", "code": "insufficient_quota", "message_semantics": "\"You exceeded your current quota, please check your plan and billing details.\" Billing/quota exhaustion; retrying never helps.", "retryable": false, "recommended_action": "Add credits / raise limits; inspect `error.code` for the specific cause.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "insufficient_quota", "code": "credit_balance_exhausted", "message_semantics": "Prepaid credit balance depleted.", "retryable": false, "recommended_action": "Add credits.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#429---credit-balance-exhausted", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "insufficient_quota", "code": "organization_spend_limit_exceeded", "message_semantics": "Organization monthly hard spend limit reached (configured via POST /v1/organization/spend_limit).", "retryable": false, "recommended_action": "Raise/remove the org limit or wait for monthly reset.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/spend-limits", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "insufficient_quota", "code": "project_spend_limit_exceeded", "message_semantics": "Project monthly hard spend limit reached.", "retryable": false, "recommended_action": "Raise/remove the project limit.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/spend-limits", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "insufficient_quota", "code": "organization_usage_limit_exceeded", "message_semantics": "OpenAI-assigned monthly usage limit (usage tier) reached; distinct from self-configured spend limits.", "retryable": false, "recommended_action": "Request a higher approved usage limit / contact support.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#429---organization-usage-limit-reached", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 429, "type": "insufficient_quota", "code": "billing_hard_limit_reached", "message_semantics": "Legacy name of the hard-limit error (pre spend-limits API).", "retryable": false, "recommended_action": "Treat like *_spend_limit_exceeded.", "status": [ "LEGACY", "UNVERIFIED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 500, "type": "server_error", "code": null, "message_semantics": "\"The server had an error while processing your request. Sorry about that!\" Transient server fault.", "retryable": true, "recommended_action": "Retry with backoff; check status.openai.com; log x-request-id.", "status": [ "DOCUMENTED", "LIVE_VERIFIED" ], "observed": { "verified_at": "2026-09-18", "note": "1 occurrence in other agents' probes (vector store file_batches cancel)" }, "source": "https://developers.openai.com/api/docs/guides/error-codes", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 503, "type": "service_unavailable_error", "code": "server_is_overloaded", "message_semantics": "\"The engine is currently overloaded\" — model temporarily lacks capacity. Formerly some endpoints returned 503 slow_down / 429 rate_limit_exceeded for this.", "retryable": true, "recommended_action": "Follow Retry-After, then retry with increasing delay. Python SDK raises InternalServerError (not RateLimitError) for 503.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#503---model-temporarily-overloaded", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 200, "type": "stream", "code": "error (SSE event)", "message_semantics": "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).", "retryable": "depends on code (server_error/rate_limit_exceeded yes; do not replay after output was consumed)", "recommended_action": "Handle stream errors explicitly; do not auto-replay a request whose output was already consumed.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/reference/resources/responses/streaming-events", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 200, "type": "response.status=incomplete", "code": "incomplete_details.reason", "message_semantics": "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`.", "retryable": false, "recommended_action": "Raise max_output_tokens / continue the conversation; content_filter -> change input.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/reference/resources/responses", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": 400, "type": "oauth", "code": "invalid_grant | invalid_subject_token | invalid_request", "message_semantics": "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.", "retryable": false, "recommended_action": "Decode the JWT locally and compare iss/aud/sub/exp/iat with the provider config.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/reference/workload-identity-federation#token-exchange-errors", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "openai", "http_status": null, "type": "sdk", "code": "APIConnectionError | APITimeoutError", "message_semantics": "Client-side: network/proxy/SSL failure or request exceeded the SDK timeout (default 600 s Python / 10 min Node).", "retryable": true, "recommended_action": "Retry with backoff; check network; raise timeout for long generations or use background mode.", "status": [ "DOCUMENTED" ], "source": "https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types", "_fragment": "generated/fragments/errors/openai-errors.json" }, { "provider": "xai", "http_status": 400, "type": "invalid-argument", "code": "invalid-argument", "category": "client", "message_semantics": "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\": \"\"}. Some 400s are a bare JSON string (multi-agent on chat completions).", "retryable": false, "recommended_action": "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).", "source": "https://docs.x.ai/developers/debugging", "observed_live": true, "live_examples": [ "POST /v1/chat/completions grok-4.20-0309-non-reasoning reasoning_effort=low -> {\"code\":\"invalid-argument\",\"error\":\"Model grok-4.20-0309-non-reasoning does not support parameter reasoningEffort.\"}", "same for grok-4.20-0309-reasoning and grok-build-0.1", "POST /v1/chat/completions grok-4.20-multi-agent-0309 -> \"Multi Agent requests are not allowed on chat completions\" (plain JSON string body)", "GET /v1/models with bogus bearer -> {\"code\":\"invalid-argument\",\"error\":\"Incorrect API key provided. You can obtain an API key from https://console.x.ai.\"}" ], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 401, "type": "unauthenticated", "code": "unauthenticated:no-credentials", "category": "auth", "message_semantics": "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).", "retryable": false, "recommended_action": "Send Authorization: Bearer ; use a Management key on management-api.x.ai.", "source": "https://docs.x.ai/developers/debugging", "observed_live": true, "live_examples": [ "GET /v1/models (no auth) -> {\"code\":\"unauthenticated:no-credentials\",\"error\":\"No credentials presented.\"}", "GET https://management-api.x.ai/auth/management-keys/validation with inference key -> 401 {code:16}" ], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 403, "type": "forbidden", "code": "permission-denied (assumed)", "category": "auth", "message_semantics": "Key lacks an ACL (api-key:endpoint: / api-key:model:), key disabled/blocked, team blocked, or ZDR/feature restriction. Docs: 'Ask your team admin for permission.'", "retryable": false, "recommended_action": "Check GET /v1/api-key (acls, api_key_blocked, api_key_disabled, team_blocked); have an admin fix ACLs via console or Management API.", "source": "https://docs.x.ai/developers/debugging", "observed_live": false, "live_examples": [], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 404, "type": "not-found", "code": "not-found", "category": "client", "message_semantics": "Unknown path, or model 'does not exist or your team 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).", "retryable": false, "recommended_action": "Check the id against GET /v1/models on the SAME base URL; contact support with team id + model name if access is expected.", "source": "https://docs.x.ai/developers/debugging", "observed_live": true, "live_examples": [ "GET /v1/models/grok-2-image -> {\"code\":\"not-found\",\"error\":\"The model grok-2-image does not exist or your team c5cb…7d93 does not have access to it. If you believe this is a mistake, please contact support and quote your team ID and the model name.\"}", "GET /v1/models/grok-voice-think-fast-2.0 -> 404 (voice models are not in the catalogue)", "GET /v1/embedding-models/grok-embedding-small -> 404", "POST /v1/chat/completions model=grok-2-image -> 404 same body" ], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 405, "type": "method-not-allowed", "code": null, "category": "client", "message_semantics": "HTTP method not supported by the path (e.g. POST to a GET-only endpoint). Empty body observed.", "retryable": false, "recommended_action": "Check the method in the REST reference.", "source": "https://docs.x.ai/developers/debugging", "observed_live": true, "live_examples": [ "DELETE /v1/models -> 405 with empty body" ], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 415, "type": "unsupported-media-type", "code": null, "category": "client", "message_semantics": "Wrong Content-Type on a POST endpoint.", "retryable": false, "recommended_action": "Send application/json (or multipart/form-data where required).", "source": "https://docs.x.ai/developers/debugging", "observed_live": false, "live_examples": [], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 422, "type": "unprocessable-entity", "code": null, "category": "client", "message_semantics": "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.", "retryable": false, "recommended_action": "Fix field types (message names the field, line and column).", "source": "https://docs.x.ai/developers/debugging", "observed_live": true, "live_examples": [ "POST /v1/tokenize-text {text: 123} -> \"Failed to deserialize the JSON body into the target type: text: invalid type: integer `123`, expected a string at line 1 column 33\"" ], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 429, "type": "too-many-requests", "code": "resource-exhausted (gRPC RESOURCE_EXHAUSTED)", "category": "rate_limit", "message_semantics": "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).", "retryable": true, "backoff": "exponential (docs example: 2**attempt seconds, 5 retries); no Retry-After documented", "recommended_action": "Back off; spread load; raise tier via spend or console request; move bulk work to the Batch API (does not count towards rate limits).", "source": "https://docs.x.ai/developers/rate-limits", "observed_live": false, "live_examples": [], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 500, "type": "internal", "code": null, "category": "server", "message_semantics": "Server-side failure (not enumerated in docs; check https://status.x.ai and the RSS feed https://status.x.ai/feed.xml).", "retryable": true, "backoff": "exponential with jitter", "recommended_action": "Retry; report persistent failures to support@x.ai with x-request-id.", "source": "https://docs.x.ai/developers/debugging", "observed_live": false, "live_examples": [], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 202, "type": "accepted (not an error)", "code": null, "category": "async", "message_semantics": "GET /v1/chat/deferred-completion/{request_id}: result not ready yet (empty body). Deferred results can be fetched exactly once within 24 h.", "retryable": true, "recommended_action": "Poll with backoff.", "source": "https://docs.x.ai/developers/advanced-api-usage/deferred-chat-completions", "observed_live": false, "live_examples": [], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": 200, "type": "usage-guideline-violation (billing event, not an HTTP error)", "code": null, "category": "policy", "message_semantics": "Requests judged to violate usage guidelines are still charged; violations caught before generation on the Responses API incur a flat $0.05 fee.", "retryable": false, "recommended_action": "Review content policy.", "source": "https://docs.x.ai/developers/pricing", "observed_live": false, "live_examples": [], "_fragment": "generated/fragments/errors/xai-errors.json" }, { "provider": "xai", "http_status": null, "type": "grpc-status-mapping", "code": "gRPC codes", "category": "reference", "message_semantics": "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).", "retryable": null, "recommended_action": "In xai-sdk, catch grpc.RpcError and inspect e.code().", "source": "https://docs.x.ai/developers/rate-limits", "observed_live": true, "live_examples": [ "management-api 401 body {\"code\": 16, \"message\": \"Invalid bearer token…\", \"details\": []}" ], "_fragment": "generated/fragments/errors/xai-errors.json" } ]