Python 88.3%
TypeScript 7.6%
Shell 4.1%
1[2 {3 "provider": "anthropic",4 "api_family": "compliance",5 "http_status": 400,6 "type": "invalid_request_error",7 "code": "compliance_api_not_enabled",8 "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.",9 "retryable": false,10 "recommended_action": "Enable the Compliance API (claude.ai > Organization settings > API for Enterprise; Console > Settings > Security toggle for standalone Console org), then resend.",11 "backoff": null,12 "category": "invalid_request",13 "observed_live": false,14 "example": null,15 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",16 "_fragment": "generated/fragments/errors/anthropic-compliance.json"17 },18 {19 "provider": "anthropic",20 "api_family": "compliance",21 "http_status": 400,22 "type": "invalid_request_error",23 "code": "unknown_query_parameter",24 "message_semantics": "`Unknown query parameter: 'created_at[gte]'. Did you mean 'created_at.gte'?` — unrecognized params are rejected, not ignored.",25 "retryable": false,26 "recommended_action": "Use dot notation for ranges (created_at.gte), `[]` suffix for arrays (activity_types[]), and after_id/before_id/page per endpoint.",27 "backoff": null,28 "category": "invalid_request",29 "observed_live": false,30 "example": null,31 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",32 "_fragment": "generated/fragments/errors/anthropic-compliance.json"33 },34 {35 "provider": "anthropic",36 "api_family": "compliance",37 "http_status": 400,38 "type": "invalid_request_error",39 "code": "invalid_parameter_value",40 "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.",41 "retryable": false,42 "recommended_action": "Correct the named parameter; respect per-endpoint limit maxima; RFC 3339 timestamps with explicit UTC offset.",43 "backoff": null,44 "category": "invalid_request",45 "observed_live": false,46 "example": null,47 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",48 "_fragment": "generated/fragments/errors/anthropic-compliance.json"49 },50 {51 "provider": "anthropic",52 "api_family": "compliance",53 "http_status": 400,54 "type": "invalid_request_error",55 "code": "invalid_pagination_cursor",56 "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).",57 "retryable": false,58 "recommended_action": "Treat cursors as opaque; copy first_id/last_id/next_page unchanged; on expiry restart without page.",59 "backoff": null,60 "category": "invalid_request",61 "observed_live": false,62 "example": null,63 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",64 "_fragment": "generated/fragments/errors/anthropic-compliance.json"65 },66 {67 "provider": "anthropic",68 "api_family": "compliance",69 "http_status": 401,70 "type": "authentication_error",71 "code": "api_key_invalid",72 "message_semantics": "`API key is invalid.` — value does not match a usable Compliance Access Key / Admin API key (truncated/altered).",73 "retryable": false,74 "recommended_action": "Compare stored secret; create a new key if the copy is wrong.",75 "backoff": null,76 "category": "authentication",77 "observed_live": false,78 "example": null,79 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",80 "_fragment": "generated/fragments/errors/anthropic-compliance.json"81 },82 {83 "provider": "anthropic",84 "api_family": "compliance",85 "http_status": 401,86 "type": "authentication_error",87 "code": "api_key_deactivated",88 "message_semantics": "`API key has been deactivated.` — key disabled or deleted.",89 "retryable": false,90 "recommended_action": "Re-enable if only disabled; otherwise create a new key and rotate.",91 "backoff": null,92 "category": "authentication",93 "observed_live": false,94 "example": null,95 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",96 "_fragment": "generated/fragments/errors/anthropic-compliance.json"97 },98 {99 "provider": "anthropic",100 "api_family": "compliance",101 "http_status": 401,102 "type": "authentication_error",103 "code": "api_key_expired",104 "message_semantics": "`API key has expired.` — Admin API key past its expiration (Compliance Access Keys have no expiry).",105 "retryable": false,106 "recommended_action": "Create a new key and update the integration.",107 "backoff": null,108 "category": "authentication",109 "observed_live": false,110 "example": null,111 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",112 "_fragment": "generated/fragments/errors/anthropic-compliance.json"113 },114 {115 "provider": "anthropic",116 "api_family": "compliance",117 "http_status": 403,118 "type": "permission_error",119 "code": "insufficient_scope_activities",120 "message_semantics": "`Missing required scopes. Got: [...] Needed one of: ['read:compliance_activities', 'read:org_audit']` on GET /v1/compliance/activities.",121 "retryable": false,122 "recommended_action": "Create a Compliance Access Key with read:compliance_activities, or use an Admin API key created while the Compliance API was enabled.",123 "backoff": null,124 "category": "permission",125 "observed_live": false,126 "example": null,127 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",128 "_fragment": "generated/fragments/errors/anthropic-compliance.json"129 },130 {131 "provider": "anthropic",132 "api_family": "compliance",133 "http_status": 403,134 "type": "permission_error",135 "code": "insufficient_scope_org_data",136 "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.",137 "retryable": false,138 "recommended_action": "Create a new Compliance Access Key with read:compliance_org_data.",139 "backoff": null,140 "category": "permission",141 "observed_live": false,142 "example": null,143 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",144 "_fragment": "generated/fragments/errors/anthropic-compliance.json"145 },146 {147 "provider": "anthropic",148 "api_family": "compliance",149 "http_status": 403,150 "type": "permission_error",151 "code": "retired_scope_org_settings",152 "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.",153 "retryable": false,154 "recommended_action": "Create a new key with read:compliance_org_data, migrate, delete the old key.",155 "backoff": null,156 "category": "permission",157 "observed_live": false,158 "example": null,159 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",160 "_fragment": "generated/fragments/errors/anthropic-compliance.json"161 },162 {163 "provider": "anthropic",164 "api_family": "compliance",165 "http_status": 403,166 "type": "permission_error",167 "code": "insufficient_scope_user_data",168 "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.",169 "retryable": false,170 "recommended_action": "Use a Compliance Access Key created in claude.ai with read:compliance_user_data.",171 "backoff": null,172 "category": "permission",173 "observed_live": false,174 "example": null,175 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",176 "_fragment": "generated/fragments/errors/anthropic-compliance.json"177 },178 {179 "provider": "anthropic",180 "api_family": "compliance",181 "http_status": 403,182 "type": "permission_error",183 "code": "insufficient_scope_delete",184 "message_semantics": "`… Needed: ['delete:compliance_user_data']` on DELETE chats/files/projects/documents.",185 "retryable": false,186 "recommended_action": "Create a separate key carrying delete:compliance_user_data (keep read and delete keys separate).",187 "backoff": null,188 "category": "permission",189 "observed_live": false,190 "example": null,191 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",192 "_fragment": "generated/fragments/errors/anthropic-compliance.json"193 },194 {195 "provider": "anthropic",196 "api_family": "compliance",197 "http_status": 404,198 "type": "not_found_error",199 "code": "request_not_authenticated",200 "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.",201 "retryable": false,202 "recommended_action": "Send an sk-ant-api01- or sk-ant-admin01- key in x-api-key; check the path against the reference.",203 "backoff": null,204 "category": "not_found",205 "observed_live": false,206 "example": null,207 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",208 "_fragment": "generated/fragments/errors/anthropic-compliance.json"209 },210 {211 "provider": "anthropic",212 "api_family": "compliance",213 "http_status": 404,214 "type": "not_found_error",215 "code": "chat_not_found",216 "message_semantics": "`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).",217 "retryable": false,218 "recommended_action": "Reconcile against claude_chat_created / claude_chat_viewed activities; drop the ID from the queue.",219 "backoff": null,220 "category": "not_found",221 "observed_live": false,222 "example": null,223 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",224 "_fragment": "generated/fragments/errors/anthropic-compliance.json"225 },226 {227 "provider": "anthropic",228 "api_family": "compliance",229 "http_status": 404,230 "type": "not_found_error",231 "code": "file_not_found",232 "message_semantics": "`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.",233 "retryable": false,234 "recommended_action": "Reconcile against claude_file_uploaded / claude_file_deleted / claude_chat_deleted activities.",235 "backoff": null,236 "category": "not_found",237 "observed_live": false,238 "example": null,239 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",240 "_fragment": "generated/fragments/errors/anthropic-compliance.json"241 },242 {243 "provider": "anthropic",244 "api_family": "compliance",245 "http_status": 404,246 "type": "not_found_error",247 "code": "generated_file_or_artifact_not_found",248 "message_semantics": "`Generated file not found: '…'` (metadata) / `Generated file content not found: '…'` (content) / `Artifact version not found: '…'` (both artifact endpoints) — deleted with their chat.",249 "retryable": false,250 "recommended_action": "Look up the chat via Get chat messages; if deleted_at set, remove from queue.",251 "backoff": null,252 "category": "not_found",253 "observed_live": false,254 "example": null,255 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",256 "_fragment": "generated/fragments/errors/anthropic-compliance.json"257 },258 {259 "provider": "anthropic",260 "api_family": "compliance",261 "http_status": 404,262 "type": "not_found_error",263 "code": "project_not_found",264 "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).",265 "retryable": false,266 "recommended_action": "Reconcile against claude_project_created / claude_project_deleted activities.",267 "backoff": null,268 "category": "not_found",269 "observed_live": false,270 "example": null,271 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",272 "_fragment": "generated/fragments/errors/anthropic-compliance.json"273 },274 {275 "provider": "anthropic",276 "api_family": "compliance",277 "http_status": 404,278 "type": "not_found_error",279 "code": "project_document_not_found",280 "message_semantics": "`No project document found with the provided id.` / `…, or it has already been deleted.` (DELETE) — text project documents (claude_proj_doc_) only.",281 "retryable": false,282 "recommended_action": "List current attachments via GET /v1/compliance/apps/projects/{project_id}/attachments.",283 "backoff": null,284 "category": "not_found",285 "observed_live": false,286 "example": null,287 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",288 "_fragment": "generated/fragments/errors/anthropic-compliance.json"289 },290 {291 "provider": "anthropic",292 "api_family": "compliance",293 "http_status": 404,294 "type": "not_found_error",295 "code": "local_session_not_found",296 "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.",297 "retryable": false,298 "recommended_action": "Confirm via the local session list; if absent, transcript is not retrievable.",299 "backoff": null,300 "category": "not_found",301 "observed_live": false,302 "example": null,303 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",304 "_fragment": "generated/fragments/errors/anthropic-compliance.json"305 },306 {307 "provider": "anthropic",308 "api_family": "compliance",309 "http_status": 404,310 "type": "not_found_error",311 "code": "local_sessions_not_available",312 "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.",313 "retryable": true,314 "recommended_action": "Keep queued IDs; retry on the next scheduled run; if persistent contact Anthropic with request-id.",315 "backoff": null,316 "category": "not_found",317 "observed_live": false,318 "example": null,319 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",320 "_fragment": "generated/fragments/errors/anthropic-compliance.json"321 },322 {323 "provider": "anthropic",324 "api_family": "compliance",325 "http_status": 404,326 "type": "not_found_error",327 "code": "remote_session_not_found",328 "message_semantics": "`Remote session not found.` — `cse_` ID missing/deleted, outside scope, or session still `pending` (no transcript yet). Malformed ID → 400.",329 "retryable": "conditional",330 "recommended_action": "Check status via the remote session list; retry after it leaves pending; deleted sessions are gone.",331 "backoff": null,332 "category": "not_found",333 "observed_live": false,334 "example": null,335 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",336 "_fragment": "generated/fragments/errors/anthropic-compliance.json"337 },338 {339 "provider": "anthropic",340 "api_family": "compliance",341 "http_status": 404,342 "type": "not_found_error",343 "code": "organization_role_or_group_not_found",344 "message_semantics": "`The \"<org_uuid>\" organization does not exist or the requester is not authorized to access it.` / `Role not found.` / `Group not found.`",345 "retryable": false,346 "recommended_action": "Verify the ID against the corresponding list endpoint.",347 "backoff": null,348 "category": "not_found",349 "observed_live": false,350 "example": null,351 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",352 "_fragment": "generated/fragments/errors/anthropic-compliance.json"353 },354 {355 "provider": "anthropic",356 "api_family": "compliance",357 "http_status": 404,358 "type": "not_found_error",359 "code": "organization_settings_not_available",360 "message_semantics": "`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).",361 "retryable": false,362 "recommended_action": "Verify against List organizations; if a known-good ID still 404s, contact your Anthropic representative.",363 "backoff": null,364 "category": "not_found",365 "observed_live": false,366 "example": null,367 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",368 "_fragment": "generated/fragments/errors/anthropic-compliance.json"369 },370 {371 "provider": "anthropic",372 "api_family": "compliance",373 "http_status": 409,374 "type": "invalid_request_error",375 "code": "project_has_attached_chats",376 "message_semantics": "`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).",377 "retryable": false,378 "recommended_action": "List chats with user_ids[] + project_ids[], delete or detach each, retry the project delete.",379 "backoff": null,380 "category": "invalid_request",381 "observed_live": false,382 "example": null,383 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",384 "_fragment": "generated/fragments/errors/anthropic-compliance.json"385 },386 {387 "provider": "anthropic",388 "api_family": "compliance",389 "http_status": 429,390 "type": "rate_limit_error",391 "code": "compliance_rate_limit_exceeded",392 "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).",393 "retryable": true,394 "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.",395 "backoff": "retry-after header; else exponential 1s doubling to 60s",396 "category": "rate_limit",397 "observed_live": false,398 "example": null,399 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",400 "_fragment": "generated/fragments/errors/anthropic-compliance.json"401 },402 {403 "provider": "anthropic",404 "http_status": 500,405 "type": "api_error",406 "code": null,407 "message_semantics": "Unexpected internal error.",408 "retryable": true,409 "recommended_action": "Retry with exponential backoff; if persistent, contact support with request_id.",410 "status": [411 "DOCUMENTED"412 ],413 "source": "https://platform.claude.com/docs/en/api/errors",414 "_fragment": "generated/fragments/errors/anthropic-errors.json"415 },416 {417 "provider": "anthropic",418 "api_family": "compliance",419 "http_status": "502/503/504/529",420 "type": null,421 "code": null,422 "message_semantics": "Transient upstream/overload errors.",423 "retryable": true,424 "recommended_action": "Retry with exponential backoff; check status.anthropic.com. Exception: some local-session 503s are not transient (see overloaded_error).",425 "backoff": "exponential 1s→60s",426 "category": "capacity",427 "observed_live": false,428 "example": null,429 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",430 "_fragment": "generated/fragments/errors/anthropic-compliance.json"431 },432 {433 "provider": "anthropic",434 "api_family": "compliance",435 "http_status": 503,436 "type": "overloaded_error",437 "code": "local_sessions_index_unavailable",438 "message_semantics": "`The local-sessions index is temporarily unavailable. Try again shortly.` — transient.",439 "retryable": true,440 "recommended_action": "Retry with backoff; do not advance page cursor.",441 "backoff": "exponential",442 "category": "overload",443 "observed_live": false,444 "example": null,445 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",446 "_fragment": "generated/fragments/errors/anthropic-compliance.json"447 },448 {449 "provider": "anthropic",450 "api_family": "compliance",451 "http_status": 503,452 "type": "overloaded_error",453 "code": "local_sessions_captured_content_unavailable",454 "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).",455 "retryable": "conditional",456 "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.",457 "backoff": "exponential",458 "category": "overload",459 "observed_live": false,460 "example": null,461 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",462 "_fragment": "generated/fragments/errors/anthropic-compliance.json"463 },464 {465 "provider": "anthropic",466 "api_family": "compliance",467 "http_status": 503,468 "type": "overloaded_error",469 "code": "local_sessions_retention_overrides_unavailable",470 "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.",471 "retryable": "conditional",472 "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).",473 "backoff": "retry on a later run",474 "category": "overload",475 "observed_live": false,476 "example": null,477 "source": "https://platform.claude.com/docs/en/manage-claude/compliance-errors",478 "_fragment": "generated/fragments/errors/anthropic-compliance.json"479 },480 {481 "provider": "anthropic",482 "http_status": 400,483 "type": "invalid_request_error",484 "code": null,485 "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.",486 "retryable": false,487 "recommended_action": "Fix the request (message names the field, e.g. 'max_tokens: Field required'). Do not retry unchanged.",488 "status": [489 "DOCUMENTED",490 "LIVE_VERIFIED"491 ],492 "source": "https://platform.claude.com/docs/en/api/errors",493 "live_messages": [494 "max_tokens: Field required",495 "max_tokens: 1000000 > 64000, which is the maximum allowed number of output tokens for claude-haiku-4-5-20251001",496 "temperature: range: 0..1",497 "top_k: Input should be a valid integer",498 "`temperature` and `top_p` cannot both be specified for this model. Please use only one.",499 "messages: at least one message is required",500 "The request body is not valid JSON: …",501 "anthropic-version: \"2020-01-01\" is not a valid version",502 "anthropic-version: \"2023-01-01\" not allowed for this endpoint",503 "Unexpected value(s) `…` for the `anthropic-beta` header. …",504 "This model does not support assistant message prefill. The conversation must end with a user message.",505 "adaptive thinking is not supported on this model",506 "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.",507 "Server tools are not supported in the count_tokens endpoint: web_search_20250305. Use the /v1/messages endpoint instead.",508 "'claude-haiku-4-5-20251001' does not support inference_geo.",509 "'claude-haiku-4-5-20251001' does not support the `speed` parameter. This feature is only available on supported models.",510 "betas: Extra inputs are not permitted",511 "output_format: Extra inputs are not permitted",512 "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."513 ],514 "response_headers": {515 "x-should-retry": "false"516 },517 "_fragment": "generated/fragments/errors/anthropic-errors.json"518 },519 {520 "provider": "anthropic",521 "http_status": 401,522 "type": "authentication_error",523 "code": null,524 "message_semantics": "API key malformed, revoked, expired (or bad AWS SigV4 on Claude Platform on AWS).",525 "retryable": false,526 "recommended_action": "Check the key / auth header. Live: 'invalid x-api-key'; anthropic-organization-id header absent on 401.",527 "status": [528 "DOCUMENTED",529 "LIVE_VERIFIED"530 ],531 "source": "https://platform.claude.com/docs/en/api/errors",532 "_fragment": "generated/fragments/errors/anthropic-errors.json"533 },534 {535 "provider": "anthropic",536 "http_status": 402,537 "type": "billing_error",538 "code": null,539 "message_semantics": "Billing/payment problem.",540 "retryable": false,541 "recommended_action": "Fix payment details in Console (or AWS Marketplace).",542 "status": [543 "DOCUMENTED"544 ],545 "source": "https://platform.claude.com/docs/en/api/errors",546 "_fragment": "generated/fragments/errors/anthropic-errors.json"547 },548 {549 "provider": "anthropic",550 "http_status": 403,551 "type": "permission_error",552 "code": null,553 "message_semantics": "Key lacks permission for the resource (workspace/org settings).",554 "retryable": false,555 "recommended_action": "Check organization access / workspace settings. Does NOT mean the endpoint doesn't exist.",556 "status": [557 "DOCUMENTED"558 ],559 "source": "https://platform.claude.com/docs/en/api/errors",560 "_fragment": "generated/fragments/errors/anthropic-errors.json"561 },562 {563 "provider": "anthropic",564 "http_status": 404,565 "type": "not_found_error",566 "code": null,567 "message_semantics": "Resource not found: unknown path, unknown resource id, or unknown model ('model: <id>').",568 "retryable": false,569 "recommended_action": "Check path/ids; for models, use GET /v1/models.",570 "status": [571 "DOCUMENTED",572 "LIVE_VERIFIED"573 ],574 "source": "https://platform.claude.com/docs/en/api/errors",575 "_fragment": "generated/fragments/errors/anthropic-errors.json"576 },577 {578 "provider": "anthropic",579 "http_status": 409,580 "type": "conflict_error",581 "code": null,582 "message_semantics": "Request conflicts with resource state (concurrent modification, uniqueness).",583 "retryable": true,584 "recommended_action": "Resolve the conflict then retry (SDKs retry 409 by default).",585 "status": [586 "DOCUMENTED"587 ],588 "source": "https://platform.claude.com/docs/en/api/errors",589 "_fragment": "generated/fragments/errors/anthropic-errors.json"590 },591 {592 "provider": "anthropic",593 "http_status": 413,594 "type": "request_too_large",595 "code": null,596 "message_semantics": "Body exceeds the size limit: Messages & count_tokens 32 MB, Batches 256 MB, Files 500 MB (returned by Cloudflare before the API).",597 "retryable": false,598 "recommended_action": "Shrink the request (use Files API / batches).",599 "status": [600 "DOCUMENTED"601 ],602 "source": "https://platform.claude.com/docs/en/api/errors",603 "_fragment": "generated/fragments/errors/anthropic-errors.json"604 },605 {606 "provider": "anthropic",607 "http_status": 422,608 "type": "unprocessable_entity (SDK class only)",609 "code": null,610 "message_semantics": "Not in the HTTP error list of the docs; SDKs map 422 to UnprocessableEntityError.",611 "retryable": false,612 "recommended_action": "Treat like 400.",613 "status": [614 "DOCUMENTED"615 ],616 "source": "https://platform.claude.com/docs/en/api/errors",617 "_fragment": "generated/fragments/errors/anthropic-errors.json"618 },619 {620 "provider": "anthropic",621 "http_status": 429,622 "type": "rate_limit_error",623 "code": null,624 "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.",625 "retryable": true,626 "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.",627 "status": [628 "DOCUMENTED"629 ],630 "source": "https://platform.claude.com/docs/en/api/errors",631 "response_headers": [632 "retry-after",633 "anthropic-ratelimit-*"634 ],635 "_fragment": "generated/fragments/errors/anthropic-errors.json"636 },637 {638 "provider": "anthropic",639 "http_status": 504,640 "type": "timeout_error",641 "code": null,642 "message_semantics": "Request timed out while processing.",643 "retryable": true,644 "recommended_action": "Use streaming or the Batches API for long requests; retry.",645 "status": [646 "DOCUMENTED"647 ],648 "source": "https://platform.claude.com/docs/en/api/errors",649 "_fragment": "generated/fragments/errors/anthropic-errors.json"650 },651 {652 "provider": "anthropic",653 "http_status": 529,654 "type": "overloaded_error",655 "code": null,656 "message_semantics": "API temporarily overloaded (all users); can also arrive as a mid-stream `error` event after HTTP 200.",657 "retryable": true,658 "recommended_action": "Retry with backoff; Priority Tier reduces occurrence. Handle the SSE `error` event.",659 "status": [660 "DOCUMENTED"661 ],662 "source": "https://platform.claude.com/docs/en/api/errors",663 "_fragment": "generated/fragments/errors/anthropic-errors.json"664 },665 {666 "provider": "anthropic",667 "http_status": null,668 "type": "streaming error event",669 "code": null,670 "message_semantics": "After HTTP 200 the stream may emit `event: error` with {type: error, error:{type, message}} (e.g. overloaded_error).",671 "retryable": true,672 "recommended_action": "Abort the stream, then retry (SDKs raise; Claude 4.6+: resume by sending partial text in a user message asking to continue).",673 "status": [674 "DOCUMENTED"675 ],676 "source": "https://platform.claude.com/docs/en/build-with-claude/streaming",677 "_fragment": "generated/fragments/errors/anthropic-errors.json"678 },679 {680 "provider": "anthropic",681 "http_status": null,682 "type": "x-should-retry header",683 "code": null,684 "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.",685 "retryable": null,686 "recommended_action": "Respect it when present.",687 "status": [688 "LIVE_DISCOVERED"689 ],690 "source": "https://platform.claude.com/docs/en/api/errors",691 "_fragment": "generated/fragments/errors/anthropic-errors.json"692 },693 {694 "provider": "anthropic",695 "http_status": 200,696 "type": "stop_reason: refusal",697 "code": null,698 "message_semantics": "Not an error: safety classifiers stopped generation; HTTP 200 with stop_details.category.",699 "retryable": false,700 "recommended_action": "Retry on a fallback model (server-side `fallbacks` beta or client-side), redeem fallback_credit_token.",701 "status": [702 "DOCUMENTED"703 ],704 "source": "https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons",705 "_fragment": "generated/fragments/errors/anthropic-errors.json"706 },707 {708 "provider": "anthropic",709 "http_status": null,710 "type": "tool result error codes",711 "code": null,712 "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).",713 "retryable": null,714 "recommended_action": "Inspect the result block; `too_many_requests`/`unavailable` are transient.",715 "status": [716 "DOCUMENTED"717 ],718 "source": "https://platform.claude.com/docs/en/api/messages",719 "_fragment": "generated/fragments/errors/anthropic-errors.json"720 },721 {722 "provider": "anthropic",723 "http_status": null,724 "type": "SDK retry policy",725 "code": null,726 "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').",727 "retryable": null,728 "recommended_action": "Configure max_retries / timeout; stream for large max_tokens.",729 "status": [730 "DOCUMENTED",731 "LIVE_VERIFIED"732 ],733 "source": "https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python",734 "verification_note": "constants read from installed anthropic 1.7.0 and @anthropic-ai/sdk 0.126.0",735 "_fragment": "generated/fragments/errors/anthropic-errors.json"736 },737 {738 "provider": "gemini",739 "http_status": 400,740 "type": "INVALID_ARGUMENT",741 "code": "400",742 "category": "invalid_request",743 "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).",744 "retryable": false,745 "recommended_action": "Fix the request; check API version (v1 vs v1beta) and model support for the feature; do not retry unchanged.",746 "observed_live": true,747 "example": [748 {749 "error": {750 "code": 400,751 "message": "Missing or invalid Authorization header.",752 "status": "INVALID_ARGUMENT"753 }754 }755 ],756 "status": [757 "DOCUMENTED",758 "LIVE_VERIFIED"759 ],760 "source": "https://ai.google.dev/gemini-api/docs/troubleshooting",761 "_fragment": "generated/fragments/errors/gemini-errors.json"762 },763 {764 "provider": "gemini",765 "http_status": 400,766 "type": "FAILED_PRECONDITION",767 "code": "400",768 "category": "permission",769 "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.",770 "retryable": false,771 "recommended_action": "Enable billing in AI Studio / check available-regions; for EEA/UK/CH end users use Paid Services.",772 "observed_live": false,773 "status": [774 "DOCUMENTED"775 ],776 "source": "https://ai.google.dev/gemini-api/docs/api-errors",777 "_fragment": "generated/fragments/errors/gemini-errors.json"778 },779 {780 "provider": "gemini",781 "http_status": 401,782 "type": "UNAUTHENTICATED",783 "code": "401",784 "category": "authentication",785 "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.",786 "retryable": false,787 "recommended_action": "Verify the key/token; regenerate blocked or leaked keys in AI Studio.",788 "observed_live": false,789 "status": [790 "DOCUMENTED"791 ],792 "source": "https://ai.google.dev/gemini-api/docs/api-errors",793 "_fragment": "generated/fragments/errors/gemini-errors.json"794 },795 {796 "provider": "gemini",797 "http_status": 403,798 "type": "PERMISSION_DENIED",799 "code": "403",800 "category": "permission",801 "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.",802 "retryable": false,803 "recommended_action": "Check key restrictions (Restrict to Gemini API only), project, IAM; rotate leaked keys.",804 "observed_live": false,805 "status": [806 "DOCUMENTED"807 ],808 "source": "https://ai.google.dev/gemini-api/docs/troubleshooting",809 "_fragment": "generated/fragments/errors/gemini-errors.json"810 },811 {812 "provider": "gemini",813 "http_status": 404,814 "type": "NOT_FOUND",815 "code": "404",816 "category": "not_found",817 "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.",818 "retryable": false,819 "recommended_action": "Check the id against GET /v1beta/models; for 2.5 models on new keys migrate to 3.x; for previews use /v1beta.",820 "observed_live": true,821 "example": {822 "error": {823 "code": 404,824 "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.",825 "status": "NOT_FOUND"826 }827 },828 "status": [829 "DOCUMENTED",830 "LIVE_VERIFIED"831 ],832 "source": "https://ai.google.dev/gemini-api/docs/api-errors",833 "_fragment": "generated/fragments/errors/gemini-errors.json"834 },835 {836 "provider": "gemini",837 "http_status": 409,838 "type": "ALREADY_EXISTS / ABORTED",839 "code": "409",840 "category": "invalid_request",841 "message_semantics": "Resource already exists (file search store / document names) or concurrency conflict. Interactions API codes: already_exists, aborted.",842 "retryable": "aborted: yes at application level; already_exists: no",843 "recommended_action": "Check existence before create; retry aborted operations.",844 "observed_live": false,845 "status": [846 "DOCUMENTED"847 ],848 "source": "https://ai.google.dev/gemini-api/docs/api-errors",849 "_fragment": "generated/fragments/errors/gemini-errors.json"850 },851 {852 "provider": "gemini",853 "http_status": 416,854 "type": "OUT_OF_RANGE",855 "code": "416",856 "category": "invalid_request",857 "message_semantics": "Request parameter outside the valid range (Interactions API code out_of_range).",858 "retryable": false,859 "recommended_action": "Check parameter values and limits.",860 "observed_live": false,861 "status": [862 "DOCUMENTED"863 ],864 "source": "https://ai.google.dev/gemini-api/docs/api-errors",865 "_fragment": "generated/fragments/errors/gemini-errors.json"866 },867 {868 "provider": "gemini",869 "http_status": 429,870 "type": "RESOURCE_EXHAUSTED",871 "code": "429",872 "category": "rate_limit",873 "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.",874 "retryable": true,875 "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",876 "recommended_action": "Back off; reduce request rate or context size; upgrade tier / request increase; for 'limit: 0' enable billing.",877 "observed_live": true,878 "example": {879 "error": {880 "code": 429,881 "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.",882 "status": "RESOURCE_EXHAUSTED",883 "details": [884 {885 "@type": "type.googleapis.com/google.rpc.Help"886 },887 {888 "@type": "type.googleapis.com/google.rpc.QuotaFailure",889 "violations": [890 {891 "quotaMetric": "generativelanguage.googleapis.com/generate_content_free_tier_requests",892 "quotaId": "GenerateRequestsPerDayPerProjectPerModel-FreeTier",893 "quotaDimensions": {894 "model": "gemini-3.1-pro",895 "location": "global"896 }897 }898 ]899 }900 ]901 }902 },903 "status": [904 "DOCUMENTED",905 "LIVE_VERIFIED"906 ],907 "source": "https://ai.google.dev/gemini-api/docs/rate-limits",908 "_fragment": "generated/fragments/errors/gemini-errors.json"909 },910 {911 "provider": "gemini",912 "http_status": 499,913 "type": "CANCELLED",914 "code": "499",915 "category": "timeout",916 "message_semantics": "Client closed the request before completion (Interactions API code cancelled).",917 "retryable": "n/a",918 "recommended_action": "No action; usually a client disconnect.",919 "observed_live": false,920 "status": [921 "DOCUMENTED"922 ],923 "source": "https://ai.google.dev/gemini-api/docs/api-errors",924 "_fragment": "generated/fragments/errors/gemini-errors.json"925 },926 {927 "provider": "gemini",928 "http_status": 500,929 "type": "INTERNAL",930 "code": "500",931 "category": "server_error",932 "message_semantics": "Unexpected server error; may also surface for oversized contexts or unusual inputs. Interactions code api_error.",933 "retryable": true,934 "backoff": "exponential; if persistent reduce context / switch model / report on the forum",935 "recommended_action": "Retry; reduce input; try another model.",936 "observed_live": false,937 "status": [938 "DOCUMENTED"939 ],940 "source": "https://ai.google.dev/gemini-api/docs/troubleshooting",941 "_fragment": "generated/fragments/errors/gemini-errors.json"942 },943 {944 "provider": "gemini",945 "http_status": 501,946 "type": "UNIMPLEMENTED",947 "code": "501",948 "category": "invalid_request",949 "message_semantics": "Operation/feature not implemented or not supported for this model/version (Interactions code unimplemented).",950 "retryable": false,951 "recommended_action": "Check capabilities; switch to a supported feature or API version.",952 "observed_live": false,953 "status": [954 "DOCUMENTED"955 ],956 "source": "https://ai.google.dev/gemini-api/docs/api-errors",957 "_fragment": "generated/fragments/errors/gemini-errors.json"958 },959 {960 "provider": "gemini",961 "http_status": 503,962 "type": "UNAVAILABLE",963 "code": "503",964 "category": "overload",965 "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.",966 "retryable": true,967 "backoff": "exponential with jitter; consider Priority tier for business-critical traffic, or a Flash/Lite fallback model",968 "recommended_action": "Retry with backoff; temporarily switch model.",969 "observed_live": false,970 "status": [971 "DOCUMENTED"972 ],973 "source": "https://ai.google.dev/gemini-api/docs/troubleshooting",974 "_fragment": "generated/fragments/errors/gemini-errors.json"975 },976 {977 "provider": "gemini",978 "http_status": 504,979 "type": "DEADLINE_EXCEEDED",980 "code": "504",981 "category": "timeout",982 "message_semantics": "Request did not finish within the deadline (large prompts, long thinking, Flex queueing). Interactions code deadline_exceeded.",983 "retryable": true,984 "backoff": "increase/remove client timeout (SDK http_options.timeout), use streaming, background execution or Batch",985 "recommended_action": "Raise the client deadline or use background=true / Batch API.",986 "observed_live": false,987 "status": [988 "DOCUMENTED"989 ],990 "source": "https://ai.google.dev/gemini-api/docs/api-errors",991 "_fragment": "generated/fragments/errors/gemini-errors.json"992 },993 {994 "provider": "gemini",995 "http_status": 200,996 "type": "promptFeedback.blockReason",997 "code": "SAFETY | OTHER | BLOCKLIST | PROHIBITED_CONTENT | IMAGE_SAFETY",998 "category": "content_safety",999 "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.",1000 "retryable": false,1001 "recommended_action": "Rewrite the prompt; adjust safetySettings thresholds where allowed (not for prohibited content).",1002 "observed_live": false,1003 "status": [1004 "DOCUMENTED"1005 ],1006 "source": "https://ai.google.dev/api/generate-content#BlockReason",1007 "_fragment": "generated/fragments/errors/gemini-errors.json"1008 },1009 {1010 "provider": "gemini",1011 "http_status": 200,1012 "type": "candidates[].finishReason",1013 "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",1014 "category": "content_safety",1015 "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 ...).",1016 "retryable": "MAX_TOKENS: raise maxOutputTokens / lower thinking_level; RECITATION/OTHER: change prompt; MISSING_THOUGHT_SIGNATURE: fix history",1017 "recommended_action": "Always check finishReason before reading parts; treat non-STOP as partial.",1018 "observed_live": true,1019 "status": [1020 "DOCUMENTED",1021 "LIVE_VERIFIED"1022 ],1023 "source": "https://ai.google.dev/api/generate-content#FinishReason",1024 "_fragment": "generated/fragments/errors/gemini-errors.json"1025 },1026 {1027 "provider": "gemini",1028 "http_status": 200,1029 "type": "Interactions API error object",1030 "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 | <snake_case http status>",1031 "category": "invalid_request",1032 "message_semantics": "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.",1033 "retryable": "per code (rate_limit_exceeded/too_many_requests/api_error/service_unavailable/deadline_exceeded/aborted retryable)",1034 "recommended_action": "Branch on `error.code`; HTTP status still set on non-streaming responses.",1035 "observed_live": false,1036 "status": [1037 "DOCUMENTED"1038 ],1039 "source": "https://ai.google.dev/gemini-api/docs/api-errors",1040 "_fragment": "generated/fragments/errors/gemini-errors.json"1041 },1042 {1043 "provider": "gemini",1044 "http_status": 400,1045 "type": "OpenAI-compat error envelope",1046 "code": "400 | 404 | 429 | 500",1047 "category": "invalid_request",1048 "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.",1049 "retryable": false,1050 "recommended_action": "Use Authorization: Bearer <GEMINI_API_KEY>; unwrap arrays before parsing.",1051 "observed_live": true,1052 "status": [1053 "LIVE_VERIFIED"1054 ],1055 "source": "live probe 2026-09-19",1056 "_fragment": "generated/fragments/errors/gemini-errors.json"1057 },1058 {1059 "provider": "gemini",1060 "http_status": null,1061 "type": "WebSocket close (Live API)",1062 "code": "1000-1011 + close reason",1063 "category": "timeout",1064 "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.",1065 "retryable": true,1066 "backoff": "reconnect with the sessionResumption handle (valid 2 h)",1067 "recommended_action": "Handle goAway/close, resume the session.",1068 "observed_live": false,1069 "status": [1070 "DOCUMENTED"1071 ],1072 "source": "https://ai.google.dev/gemini-api/docs/live-api/session",1073 "_fragment": "generated/fragments/errors/gemini-errors.json"1074 },1075 {1076 "provider": "openai",1077 "http_status": 400,1078 "type": "invalid_request_error",1079 "code": "invalid_type",1080 "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.",1081 "retryable": false,1082 "recommended_action": "Fix the request; never retry unchanged.",1083 "status": [1084 "LIVE_VERIFIED"1085 ],1086 "observed": {1087 "verified_at": "2026-09-18",1088 "endpoint": "POST /v1/responses",1089 "param": "max_output_tokens"1090 },1091 "source": "https://developers.openai.com/api/docs/guides/error-codes",1092 "_fragment": "generated/fragments/errors/openai-errors.json"1093 },1094 {1095 "provider": "openai",1096 "http_status": 400,1097 "type": "invalid_request_error",1098 "code": "missing_required_parameter",1099 "message_semantics": "\"Missing required parameter: 'model'.\" `param` = missing field.",1100 "retryable": false,1101 "recommended_action": "Add the parameter.",1102 "status": [1103 "LIVE_VERIFIED"1104 ],1105 "observed": {1106 "verified_at": "2026-09-18",1107 "endpoint": "POST /v1/responses"1108 },1109 "source": "https://developers.openai.com/api/docs/guides/error-codes",1110 "_fragment": "generated/fragments/errors/openai-errors.json"1111 },1112 {1113 "provider": "openai",1114 "http_status": 400,1115 "type": "invalid_request_error",1116 "code": "unknown_parameter",1117 "message_semantics": "\"Unknown parameter: 'x'.\" The API rejects unrecognised body fields (strict schema).",1118 "retryable": false,1119 "recommended_action": "Remove/rename the field; check for Chat-vs-Responses parameter differences.",1120 "status": [1121 "LIVE_VERIFIED"1122 ],1123 "observed": {1124 "verified_at": "2026-09-18",1125 "endpoint": "POST /v1/responses"1126 },1127 "source": "https://developers.openai.com/api/docs/guides/error-codes",1128 "_fragment": "generated/fragments/errors/openai-errors.json"1129 },1130 {1131 "provider": "openai",1132 "http_status": 400,1133 "type": "invalid_request_error",1134 "code": "unsupported_parameter",1135 "message_semantics": "Parameter exists but is not supported for this model/endpoint combination (e.g. `temperature` on reasoning models, `dimensions` on ada-002).",1136 "retryable": false,1137 "recommended_action": "Drop the parameter for that model.",1138 "status": [1139 "LIVE_VERIFIED"1140 ],1141 "observed": {1142 "verified_at": "2026-09-18",1143 "note": "seen in other agents' probes (tmp-live)"1144 },1145 "source": "https://developers.openai.com/api/docs/guides/error-codes",1146 "_fragment": "generated/fragments/errors/openai-errors.json"1147 },1148 {1149 "provider": "openai",1150 "http_status": 400,1151 "type": "invalid_request_error",1152 "code": "invalid_value",1153 "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.",1154 "retryable": false,1155 "recommended_action": "Correct the value; read `param` + message.",1156 "status": [1157 "LIVE_VERIFIED"1158 ],1159 "observed": {1160 "verified_at": "2026-09-18",1161 "endpoint": "POST /v1/chat/completions",1162 "param": "max_tokens"1163 },1164 "source": "https://developers.openai.com/api/docs/guides/error-codes",1165 "_fragment": "generated/fragments/errors/openai-errors.json"1166 },1167 {1168 "provider": "openai",1169 "http_status": 400,1170 "type": "invalid_request_error",1171 "code": "integer_below_min_value",1172 "message_semantics": "Integer below the allowed minimum (also `integer_above_max_value`, `string_above_max_length`, `array_above_max_length` family).",1173 "retryable": false,1174 "recommended_action": "Clamp the value.",1175 "status": [1176 "LIVE_VERIFIED"1177 ],1178 "observed": {1179 "verified_at": "2026-09-18",1180 "note": "seen in other agents' probes"1181 },1182 "source": "https://developers.openai.com/api/docs/guides/error-codes",1183 "_fragment": "generated/fragments/errors/openai-errors.json"1184 },1185 {1186 "provider": "openai",1187 "http_status": 400,1188 "type": "invalid_request_error",1189 "code": "mutually_exclusive_parameters",1190 "message_semantics": "Two body parameters cannot be combined (e.g. `previous_response_id` + `conversation`).",1191 "retryable": false,1192 "recommended_action": "Send only one of them.",1193 "status": [1194 "LIVE_VERIFIED"1195 ],1196 "observed": {1197 "verified_at": "2026-09-18",1198 "note": "seen in other agents' probes"1199 },1200 "source": "https://developers.openai.com/api/docs/guides/error-codes",1201 "_fragment": "generated/fragments/errors/openai-errors.json"1202 },1203 {1204 "provider": "openai",1205 "http_status": 400,1206 "type": "invalid_request_error",1207 "code": "invalid_json",1208 "message_semantics": "\"Invalid body: failed to parse JSON value...\" Body is not valid JSON.",1209 "retryable": false,1210 "recommended_action": "Fix serialisation (trailing commas, quotes).",1211 "status": [1212 "LIVE_VERIFIED"1213 ],1214 "observed": {1215 "verified_at": "2026-09-18",1216 "endpoint": "POST /v1/responses"1217 },1218 "source": "https://developers.openai.com/api/docs/guides/error-codes",1219 "_fragment": "generated/fragments/errors/openai-errors.json"1220 },1221 {1222 "provider": "openai",1223 "http_status": 400,1224 "type": "invalid_request_error",1225 "code": "unsupported_content_type",1226 "message_semantics": "\"Unsupported content type: 'text/plain'. This API method only accepts 'application/json' requests\".",1227 "retryable": false,1228 "recommended_action": "Send Content-Type: application/json (multipart/form-data only for file endpoints).",1229 "status": [1230 "LIVE_VERIFIED"1231 ],1232 "observed": {1233 "verified_at": "2026-09-18",1234 "endpoint": "POST /v1/responses"1235 },1236 "source": "https://developers.openai.com/api/docs/guides/error-codes",1237 "_fragment": "generated/fragments/errors/openai-errors.json"1238 },1239 {1240 "provider": "openai",1241 "http_status": 400,1242 "type": "invalid_request_error",1243 "code": null,1244 "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.",1245 "retryable": false,1246 "recommended_action": "Choose an allowed tier or change project settings.",1247 "status": [1248 "DOCUMENTED"1249 ],1250 "source": "https://developers.openai.com/api/docs/guides/error-codes#400---invalid-service_tier-argument",1251 "_fragment": "generated/fragments/errors/openai-errors.json"1252 },1253 {1254 "provider": "openai",1255 "http_status": 400,1256 "type": "invalid_request_error",1257 "code": "invalid_beta",1258 "message_semantics": "Endpoint requires an `OpenAI-Beta` header value that was missing/invalid (e.g. `agents=v1`, `assistants=v2`).",1259 "retryable": false,1260 "recommended_action": "Add the documented OpenAI-Beta header.",1261 "status": [1262 "LIVE_VERIFIED"1263 ],1264 "observed": {1265 "verified_at": "2026-09-18",1266 "note": "GET /v1/agents without OpenAI-Beta (other agent's probe)"1267 },1268 "source": "https://developers.openai.com/api/reference/resources/beta",1269 "_fragment": "generated/fragments/errors/openai-errors.json"1270 },1271 {1272 "provider": "openai",1273 "http_status": 400,1274 "type": "invalid_request_error",1275 "code": "previous_response_not_found",1276 "message_semantics": "`previous_response_id` cannot be resolved (deleted, unstored `store=false`, wrong project, or WebSocket-mode state lost).",1277 "retryable": false,1278 "recommended_action": "Retry with full input context and `previous_response_id: null`.",1279 "status": [1280 "DOCUMENTED",1281 "LIVE_VERIFIED"1282 ],1283 "observed": {1284 "verified_at": "2026-09-18",1285 "note": "other agent's probe"1286 },1287 "source": "https://developers.openai.com/api/docs/guides/error-codes#websocket-mode-errors",1288 "_fragment": "generated/fragments/errors/openai-errors.json"1289 },1290 {1291 "provider": "openai",1292 "http_status": 400,1293 "type": "invalid_request_error",1294 "code": "websocket_connection_limit_reached",1295 "message_semantics": "Responses WebSocket mode connection hit the 60-minute limit.",1296 "retryable": true,1297 "recommended_action": "Open a new WebSocket connection and continue.",1298 "status": [1299 "DOCUMENTED"1300 ],1301 "source": "https://developers.openai.com/api/docs/guides/error-codes#websocket-mode-errors",1302 "_fragment": "generated/fragments/errors/openai-errors.json"1303 },1304 {1305 "provider": "openai",1306 "http_status": 400,1307 "type": "invalid_request_error",1308 "code": "context_length_exceeded",1309 "message_semantics": "Prompt + requested output exceed the model context window (\"This model's maximum context length is N tokens...\").",1310 "retryable": false,1311 "recommended_action": "Truncate/summarise input, lower max output tokens, or use Responses `truncation: \"auto\"`.",1312 "status": [1313 "DOCUMENTED"1314 ],1315 "note": "Documented historically in the error-codes guide/community; in our probe an oversized max_tokens returned code `invalid_value` instead.",1316 "source": "https://developers.openai.com/api/docs/guides/error-codes",1317 "_fragment": "generated/fragments/errors/openai-errors.json"1318 },1319 {1320 "provider": "openai",1321 "http_status": 400,1322 "type": "invalid_request_error",1323 "code": "invalid_prompt",1324 "message_semantics": "Prompt rejected (e.g. flagged by safety system / unsupported content) before generation.",1325 "retryable": false,1326 "recommended_action": "Change the prompt; do not retry unchanged.",1327 "status": [1328 "DOCUMENTED"1329 ],1330 "source": "https://developers.openai.com/api/docs/guides/moderation",1331 "_fragment": "generated/fragments/errors/openai-errors.json"1332 },1333 {1334 "provider": "openai",1335 "http_status": 400,1336 "type": "image_generation_user_error",1337 "code": "moderation_blocked",1338 "message_semantics": "Image prompt/input blocked by moderation; optional `error.moderation_details {moderation_stage: input|output, categories[]}`.",1339 "retryable": false,1340 "recommended_action": "Do not auto-retry; change prompt/input.",1341 "status": [1342 "DOCUMENTED"1343 ],1344 "source": "https://developers.openai.com/api/docs/guides/image-generation",1345 "_fragment": "generated/fragments/errors/openai-errors.json"1346 },1347 {1348 "provider": "openai",1349 "http_status": 400,1350 "type": "invalid_request_error",1351 "code": "content_policy_violation",1352 "message_semantics": "Request violates usage policies (legacy images/moderation wording; current image endpoints use `moderation_blocked`).",1353 "retryable": false,1354 "recommended_action": "Change the content.",1355 "status": [1356 "DOCUMENTED",1357 "LEGACY"1358 ],1359 "source": "https://developers.openai.com/api/docs/guides/error-codes",1360 "_fragment": "generated/fragments/errors/openai-errors.json"1361 },1362 {1363 "provider": "openai",1364 "http_status": 400,1365 "type": "invalid_request_error",1366 "code": "invalid_image / invalid_image_format / image_parse_error",1367 "message_semantics": "Image input cannot be decoded, wrong format, or too large.",1368 "retryable": false,1369 "recommended_action": "Re-encode (PNG/JPEG/WEBP/GIF), respect size limits.",1370 "status": [1371 "DOCUMENTED"1372 ],1373 "source": "https://developers.openai.com/api/docs/guides/images-vision",1374 "_fragment": "generated/fragments/errors/openai-errors.json"1375 },1376 {1377 "provider": "openai",1378 "http_status": 400,1379 "type": "invalid_request_error",1380 "code": "response_already_completed",1381 "message_semantics": "Responses multi-agent `response.inject` failed because the target response already completed (delivered as stream event `response.inject.failed`).",1382 "retryable": false,1383 "recommended_action": "Re-send the injected input in the next turn.",1384 "status": [1385 "DOCUMENTED",1386 "BETA"1387 ],1388 "source": "https://developers.openai.com/api/docs/guides/responses-multi-agent",1389 "_fragment": "generated/fragments/errors/openai-errors.json"1390 },1391 {1392 "provider": "openai",1393 "http_status": 401,1394 "type": "invalid_request_error",1395 "code": "invalid_api_key",1396 "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`).",1397 "retryable": false,1398 "recommended_action": "Fix/rotate the key; SDKs raise AuthenticationError.",1399 "status": [1400 "DOCUMENTED",1401 "LIVE_VERIFIED"1402 ],1403 "observed": {1404 "verified_at": "2026-09-18",1405 "endpoint": "GET /v1/models",1406 "request_note": "Authorization: Bearer sk-invalid (literal)"1407 },1408 "source": "https://developers.openai.com/api/docs/guides/error-codes#401---incorrect-api-key-provided",1409 "_fragment": "generated/fragments/errors/openai-errors.json"1410 },1411 {1412 "provider": "openai",1413 "http_status": 401,1414 "type": "invalid_request_error",1415 "code": null,1416 "message_semantics": "\"You must be a member of an organization to use the API\" / revoked key / key from another org.",1417 "retryable": false,1418 "recommended_action": "Get invited to an organization or use a valid key.",1419 "status": [1420 "DOCUMENTED"1421 ],1422 "source": "https://developers.openai.com/api/docs/guides/error-codes#401---you-must-be-a-member-of-an-organization-to-use-the-api",1423 "_fragment": "generated/fragments/errors/openai-errors.json"1424 },1425 {1426 "provider": "openai",1427 "http_status": 401,1428 "type": "invalid_request_error",1429 "code": "mismatched_organization",1430 "message_semantics": "\"OpenAI-Organization header should match organization for API key\".",1431 "retryable": false,1432 "recommended_action": "Remove the header or use the key's organization id.",1433 "status": [1434 "LIVE_VERIFIED"1435 ],1436 "observed": {1437 "verified_at": "2026-09-18",1438 "endpoint": "GET /v1/models"1439 },1440 "source": "https://developers.openai.com/api/reference/overview#authentication",1441 "_fragment": "generated/fragments/errors/openai-errors.json"1442 },1443 {1444 "provider": "openai",1445 "http_status": 401,1446 "type": "invalid_request_error",1447 "code": "invalid_project",1448 "message_semantics": "\"No such project: 'proj_...'\" when OpenAI-Project does not exist / does not belong to the key.",1449 "retryable": false,1450 "recommended_action": "Fix the OpenAI-Project header (only meaningful with legacy user keys).",1451 "status": [1452 "LIVE_VERIFIED"1453 ],1454 "observed": {1455 "verified_at": "2026-09-18",1456 "endpoint": "GET /v1/models"1457 },1458 "source": "https://developers.openai.com/api/reference/overview#authentication",1459 "_fragment": "generated/fragments/errors/openai-errors.json"1460 },1461 {1462 "provider": "openai",1463 "http_status": 401,1464 "type": "invalid_request_error",1465 "code": "ip_not_authorized",1466 "message_semantics": "Request IP is outside the active IP allowlist of the project/org.",1467 "retryable": false,1468 "recommended_action": "Send from an allowed IP or update the allowlist.",1469 "status": [1470 "DOCUMENTED"1471 ],1472 "source": "https://developers.openai.com/api/docs/guides/ip-allowlist",1473 "_fragment": "generated/fragments/errors/openai-errors.json"1474 },1475 {1476 "provider": "openai",1477 "http_status": 403,1478 "type": null,1479 "code": null,1480 "message_semantics": "mtls.auth.openai.com: any method/path other than exact POST /oauth/token.",1481 "retryable": false,1482 "recommended_action": "Use POST https://mtls.auth.openai.com/oauth/token.",1483 "status": [1484 "DOCUMENTED"1485 ],1486 "source": "https://developers.openai.com/api/reference/workload-identity-federation",1487 "_fragment": "generated/fragments/errors/openai-errors.json"1488 },1489 {1490 "provider": "openai",1491 "http_status": 403,1492 "type": "invalid_request_error",1493 "code": "insufficient_permissions",1494 "message_semantics": "Structured variant of the scope error: {\"error\": {\"message\": \"... Missing scopes: api.external_storage.read ...\", \"type\": \"invalid_request_error\", \"code\": \"insufficient_permissions\"}}.",1495 "retryable": false,1496 "recommended_action": "Use a key with the required scope.",1497 "status": [1498 "LIVE_VERIFIED",1499 "ACCOUNT_RESTRICTED"1500 ],1501 "observed": {1502 "verified_at": "2026-09-18",1503 "endpoint": "GET /v1/organization/external_storage"1504 },1505 "source": "https://developers.openai.com/api/reference/administration/overview",1506 "_fragment": "generated/fragments/errors/openai-errors.json"1507 },1508 {1509 "provider": "openai",1510 "http_status": 403,1511 "type": "invalid_request_error",1512 "code": "misalignment_policy_violation",1513 "message_semantics": "Misalignment monitoring blocked the request before streaming; Error object may carry `misalignment{classification, message, continuation_instruction}`.",1514 "retryable": false,1515 "recommended_action": "Stop the workflow; do not auto-retry; surface to an operator.",1516 "status": [1517 "DOCUMENTED"1518 ],1519 "source": "https://developers.openai.com/api/docs/guides/safety-checks/misalignment-monitoring",1520 "_fragment": "generated/fragments/errors/openai-errors.json"1521 },1522 {1523 "provider": "openai",1524 "http_status": 403,1525 "type": "invalid_request_error",1526 "code": "cyber_policy",1527 "message_semantics": "Cybersecurity safeguard classified the request as suspicious (ZDR orgs); may arrive mid-stream as an error event.",1528 "retryable": false,1529 "recommended_action": "Do not retry; see appeals in the cybersecurity guide.",1530 "status": [1531 "DOCUMENTED"1532 ],1533 "source": "https://developers.openai.com/api/docs/guides/safety-checks/cybersecurity",1534 "_fragment": "generated/fragments/errors/openai-errors.json"1535 },1536 {1537 "provider": "openai",1538 "http_status": 403,1539 "type": "invalid_request_error",1540 "code": "unsupported_country_region_territory",1541 "message_semantics": "\"Country, region, or territory not supported\".",1542 "retryable": false,1543 "recommended_action": "See the supported countries page.",1544 "status": [1545 "DOCUMENTED"1546 ],1547 "source": "https://developers.openai.com/api/docs/guides/error-codes#api-errors",1548 "_fragment": "generated/fragments/errors/openai-errors.json"1549 },1550 {1551 "provider": "openai",1552 "http_status": 404,1553 "type": "invalid_request_error",1554 "code": "model_not_found",1555 "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).",1556 "retryable": false,1557 "recommended_action": "Check GET /v1/models; check project model_permissions; a 404 does not prove the model does not exist.",1558 "status": [1559 "DOCUMENTED",1560 "LIVE_VERIFIED"1561 ],1562 "observed": {1563 "verified_at": "2026-09-18",1564 "endpoint": "POST /v1/responses"1565 },1566 "source": "https://developers.openai.com/api/docs/guides/error-codes",1567 "_fragment": "generated/fragments/errors/openai-errors.json"1568 },1569 {1570 "provider": "openai",1571 "http_status": 404,1572 "type": "invalid_request_error",1573 "code": null,1574 "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`.",1575 "retryable": false,1576 "recommended_action": "Verify the id and project; `store=false` responses are never retrievable.",1577 "status": [1578 "LIVE_VERIFIED"1579 ],1580 "observed": {1581 "verified_at": "2026-09-18",1582 "endpoint": "GET /v1/responses/{id}"1583 },1584 "source": "https://developers.openai.com/api/docs/guides/error-codes",1585 "_fragment": "generated/fragments/errors/openai-errors.json"1586 },1587 {1588 "provider": "openai",1589 "http_status": 404,1590 "type": "not_found_error",1591 "code": "not_found_error",1592 "message_semantics": "Stainless-style typed 404 used by newer resources (vaults, skills, chatkit, agents sessions, videos).",1593 "retryable": false,1594 "recommended_action": "Verify the id.",1595 "status": [1596 "LIVE_VERIFIED"1597 ],1598 "observed": {1599 "verified_at": "2026-09-18",1600 "note": "other agents' probes"1601 },1602 "source": "https://developers.openai.com/api/docs/guides/error-codes",1603 "_fragment": "generated/fragments/errors/openai-errors.json"1604 },1605 {1606 "provider": "openai",1607 "http_status": 404,1608 "type": null,1609 "code": null,1610 "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).",1611 "retryable": false,1612 "recommended_action": "Check the path and API version prefix /v1.",1613 "status": [1614 "LIVE_VERIFIED"1615 ],1616 "observed": {1617 "verified_at": "2026-09-18",1618 "endpoint": "GET /v1/this_endpoint_does_not_exist"1619 },1620 "source": "https://developers.openai.com/api/reference/overview",1621 "_fragment": "generated/fragments/errors/openai-errors.json"1622 },1623 {1624 "provider": "openai",1625 "http_status": 405,1626 "type": "invalid_request_error",1627 "code": null,1628 "message_semantics": "\"Invalid method for URL (PATCH /v1/models)\".",1629 "retryable": false,1630 "recommended_action": "Use the documented method (OpenAI uses POST for updates, never PATCH/PUT).",1631 "status": [1632 "LIVE_VERIFIED"1633 ],1634 "observed": {1635 "verified_at": "2026-09-18",1636 "endpoint": "PATCH /v1/models"1637 },1638 "source": "https://developers.openai.com/api/reference/overview",1639 "_fragment": "generated/fragments/errors/openai-errors.json"1640 },1641 {1642 "provider": "openai",1643 "http_status": 409,1644 "type": "invalid_request_error",1645 "code": null,1646 "message_semantics": "Conflict: resource modified concurrently / state conflict (SDK ConflictError). Example codes seen: `upload_not_pending` (400 in practice).",1647 "retryable": true,1648 "recommended_action": "Re-read the resource and retry once.",1649 "status": [1650 "DOCUMENTED"1651 ],1652 "source": "https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types",1653 "_fragment": "generated/fragments/errors/openai-errors.json"1654 },1655 {1656 "provider": "openai",1657 "http_status": 422,1658 "type": "invalid_request_error",1659 "code": null,1660 "message_semantics": "Unprocessable entity: well-formed but cannot be processed (SDK UnprocessableEntityError).",1661 "retryable": true,1662 "recommended_action": "Docs say 'try the request again'; validate content first.",1663 "status": [1664 "DOCUMENTED"1665 ],1666 "source": "https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types",1667 "_fragment": "generated/fragments/errors/openai-errors.json"1668 },1669 {1670 "provider": "openai",1671 "http_status": 429,1672 "type": "rate_limit_error",1673 "code": "rate_limit_exceeded",1674 "message_semantics": "\"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.",1675 "retryable": true,1676 "recommended_action": "Wait >= Retry-After (else exponential backoff + jitter, bounded attempts). SDKs auto-retry 2x by default. Failed requests still count.",1677 "status": [1678 "DOCUMENTED"1679 ],1680 "source": "https://developers.openai.com/api/docs/guides/rate-limits",1681 "_fragment": "generated/fragments/errors/openai-errors.json"1682 },1683 {1684 "provider": "openai",1685 "http_status": 429,1686 "type": "rate_limit_error",1687 "code": "slow_down",1688 "message_semantics": "Traffic ramped too fast (can happen under RPM/TPM). Rule of thumb: above 1M TPM grow <= 50% per 15 min.",1689 "retryable": true,1690 "recommended_action": "Follow Retry-After, reduce rate, ramp gradually.",1691 "status": [1692 "DOCUMENTED"1693 ],1694 "source": "https://developers.openai.com/api/docs/guides/error-codes#429---slow-down",1695 "_fragment": "generated/fragments/errors/openai-errors.json"1696 },1697 {1698 "provider": "openai",1699 "http_status": 429,1700 "type": "insufficient_quota",1701 "code": "insufficient_quota",1702 "message_semantics": "\"You exceeded your current quota, please check your plan and billing details.\" Billing/quota exhaustion; retrying never helps.",1703 "retryable": false,1704 "recommended_action": "Add credits / raise limits; inspect `error.code` for the specific cause.",1705 "status": [1706 "DOCUMENTED"1707 ],1708 "source": "https://developers.openai.com/api/docs/guides/error-codes",1709 "_fragment": "generated/fragments/errors/openai-errors.json"1710 },1711 {1712 "provider": "openai",1713 "http_status": 429,1714 "type": "insufficient_quota",1715 "code": "credit_balance_exhausted",1716 "message_semantics": "Prepaid credit balance depleted.",1717 "retryable": false,1718 "recommended_action": "Add credits.",1719 "status": [1720 "DOCUMENTED"1721 ],1722 "source": "https://developers.openai.com/api/docs/guides/error-codes#429---credit-balance-exhausted",1723 "_fragment": "generated/fragments/errors/openai-errors.json"1724 },1725 {1726 "provider": "openai",1727 "http_status": 429,1728 "type": "insufficient_quota",1729 "code": "organization_spend_limit_exceeded",1730 "message_semantics": "Organization monthly hard spend limit reached (configured via POST /v1/organization/spend_limit).",1731 "retryable": false,1732 "recommended_action": "Raise/remove the org limit or wait for monthly reset.",1733 "status": [1734 "DOCUMENTED"1735 ],1736 "source": "https://developers.openai.com/api/docs/guides/spend-limits",1737 "_fragment": "generated/fragments/errors/openai-errors.json"1738 },1739 {1740 "provider": "openai",1741 "http_status": 429,1742 "type": "insufficient_quota",1743 "code": "project_spend_limit_exceeded",1744 "message_semantics": "Project monthly hard spend limit reached.",1745 "retryable": false,1746 "recommended_action": "Raise/remove the project limit.",1747 "status": [1748 "DOCUMENTED"1749 ],1750 "source": "https://developers.openai.com/api/docs/guides/spend-limits",1751 "_fragment": "generated/fragments/errors/openai-errors.json"1752 },1753 {1754 "provider": "openai",1755 "http_status": 429,1756 "type": "insufficient_quota",1757 "code": "organization_usage_limit_exceeded",1758 "message_semantics": "OpenAI-assigned monthly usage limit (usage tier) reached; distinct from self-configured spend limits.",1759 "retryable": false,1760 "recommended_action": "Request a higher approved usage limit / contact support.",1761 "status": [1762 "DOCUMENTED"1763 ],1764 "source": "https://developers.openai.com/api/docs/guides/error-codes#429---organization-usage-limit-reached",1765 "_fragment": "generated/fragments/errors/openai-errors.json"1766 },1767 {1768 "provider": "openai",1769 "http_status": 429,1770 "type": "insufficient_quota",1771 "code": "billing_hard_limit_reached",1772 "message_semantics": "Legacy name of the hard-limit error (pre spend-limits API).",1773 "retryable": false,1774 "recommended_action": "Treat like *_spend_limit_exceeded.",1775 "status": [1776 "LEGACY",1777 "UNVERIFIED"1778 ],1779 "source": "https://developers.openai.com/api/docs/guides/error-codes",1780 "_fragment": "generated/fragments/errors/openai-errors.json"1781 },1782 {1783 "provider": "openai",1784 "http_status": 500,1785 "type": "server_error",1786 "code": null,1787 "message_semantics": "\"The server had an error while processing your request. Sorry about that!\" Transient server fault.",1788 "retryable": true,1789 "recommended_action": "Retry with backoff; check status.openai.com; log x-request-id.",1790 "status": [1791 "DOCUMENTED",1792 "LIVE_VERIFIED"1793 ],1794 "observed": {1795 "verified_at": "2026-09-18",1796 "note": "1 occurrence in other agents' probes (vector store file_batches cancel)"1797 },1798 "source": "https://developers.openai.com/api/docs/guides/error-codes",1799 "_fragment": "generated/fragments/errors/openai-errors.json"1800 },1801 {1802 "provider": "openai",1803 "http_status": 503,1804 "type": "service_unavailable_error",1805 "code": "server_is_overloaded",1806 "message_semantics": "\"The engine is currently overloaded\" — model temporarily lacks capacity. Formerly some endpoints returned 503 slow_down / 429 rate_limit_exceeded for this.",1807 "retryable": true,1808 "recommended_action": "Follow Retry-After, then retry with increasing delay. Python SDK raises InternalServerError (not RateLimitError) for 503.",1809 "status": [1810 "DOCUMENTED"1811 ],1812 "source": "https://developers.openai.com/api/docs/guides/error-codes#503---model-temporarily-overloaded",1813 "_fragment": "generated/fragments/errors/openai-errors.json"1814 },1815 {1816 "provider": "openai",1817 "http_status": 200,1818 "type": "stream",1819 "code": "error (SSE event)",1820 "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).",1821 "retryable": "depends on code (server_error/rate_limit_exceeded yes; do not replay after output was consumed)",1822 "recommended_action": "Handle stream errors explicitly; do not auto-replay a request whose output was already consumed.",1823 "status": [1824 "DOCUMENTED"1825 ],1826 "source": "https://developers.openai.com/api/reference/resources/responses/streaming-events",1827 "_fragment": "generated/fragments/errors/openai-errors.json"1828 },1829 {1830 "provider": "openai",1831 "http_status": 200,1832 "type": "response.status=incomplete",1833 "code": "incomplete_details.reason",1834 "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`.",1835 "retryable": false,1836 "recommended_action": "Raise max_output_tokens / continue the conversation; content_filter -> change input.",1837 "status": [1838 "DOCUMENTED"1839 ],1840 "source": "https://developers.openai.com/api/reference/resources/responses",1841 "_fragment": "generated/fragments/errors/openai-errors.json"1842 },1843 {1844 "provider": "openai",1845 "http_status": 400,1846 "type": "oauth",1847 "code": "invalid_grant | invalid_subject_token | invalid_request",1848 "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.",1849 "retryable": false,1850 "recommended_action": "Decode the JWT locally and compare iss/aud/sub/exp/iat with the provider config.",1851 "status": [1852 "DOCUMENTED"1853 ],1854 "source": "https://developers.openai.com/api/reference/workload-identity-federation#token-exchange-errors",1855 "_fragment": "generated/fragments/errors/openai-errors.json"1856 },1857 {1858 "provider": "openai",1859 "http_status": null,1860 "type": "sdk",1861 "code": "APIConnectionError | APITimeoutError",1862 "message_semantics": "Client-side: network/proxy/SSL failure or request exceeded the SDK timeout (default 600 s Python / 10 min Node).",1863 "retryable": true,1864 "recommended_action": "Retry with backoff; check network; raise timeout for long generations or use background mode.",1865 "status": [1866 "DOCUMENTED"1867 ],1868 "source": "https://developers.openai.com/api/docs/guides/error-codes#python-library-error-types",1869 "_fragment": "generated/fragments/errors/openai-errors.json"1870 },1871 {1872 "provider": "xai",1873 "http_status": 400,1874 "type": "invalid-argument",1875 "code": "invalid-argument",1876 "category": "client",1877 "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\": \"<message>\"}. Some 400s are a bare JSON string (multi-agent on chat completions).",1878 "retryable": false,1879 "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).",1880 "source": "https://docs.x.ai/developers/debugging",1881 "observed_live": true,1882 "live_examples": [1883 "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.\"}",1884 "same for grok-4.20-0309-reasoning and grok-build-0.1",1885 "POST /v1/chat/completions grok-4.20-multi-agent-0309 -> \"Multi Agent requests are not allowed on chat completions\" (plain JSON string body)",1886 "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.\"}"1887 ],1888 "_fragment": "generated/fragments/errors/xai-errors.json"1889 },1890 {1891 "provider": "xai",1892 "http_status": 401,1893 "type": "unauthenticated",1894 "code": "unauthenticated:no-credentials",1895 "category": "auth",1896 "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).",1897 "retryable": false,1898 "recommended_action": "Send Authorization: Bearer <XAI_API_KEY>; use a Management key on management-api.x.ai.",1899 "source": "https://docs.x.ai/developers/debugging",1900 "observed_live": true,1901 "live_examples": [1902 "GET /v1/models (no auth) -> {\"code\":\"unauthenticated:no-credentials\",\"error\":\"No credentials presented.\"}",1903 "GET https://management-api.x.ai/auth/management-keys/validation with inference key -> 401 {code:16}"1904 ],1905 "_fragment": "generated/fragments/errors/xai-errors.json"1906 },1907 {1908 "provider": "xai",1909 "http_status": 403,1910 "type": "forbidden",1911 "code": "permission-denied (assumed)",1912 "category": "auth",1913 "message_semantics": "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.'",1914 "retryable": false,1915 "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.",1916 "source": "https://docs.x.ai/developers/debugging",1917 "observed_live": false,1918 "live_examples": [],1919 "_fragment": "generated/fragments/errors/xai-errors.json"1920 },1921 {1922 "provider": "xai",1923 "http_status": 404,1924 "type": "not-found",1925 "code": "not-found",1926 "category": "client",1927 "message_semantics": "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).",1928 "retryable": false,1929 "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.",1930 "source": "https://docs.x.ai/developers/debugging",1931 "observed_live": true,1932 "live_examples": [1933 "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.\"}",1934 "GET /v1/models/grok-voice-think-fast-2.0 -> 404 (voice models are not in the catalogue)",1935 "GET /v1/embedding-models/grok-embedding-small -> 404",1936 "POST /v1/chat/completions model=grok-2-image -> 404 same body"1937 ],1938 "_fragment": "generated/fragments/errors/xai-errors.json"1939 },1940 {1941 "provider": "xai",1942 "http_status": 405,1943 "type": "method-not-allowed",1944 "code": null,1945 "category": "client",1946 "message_semantics": "HTTP method not supported by the path (e.g. POST to a GET-only endpoint). Empty body observed.",1947 "retryable": false,1948 "recommended_action": "Check the method in the REST reference.",1949 "source": "https://docs.x.ai/developers/debugging",1950 "observed_live": true,1951 "live_examples": [1952 "DELETE /v1/models -> 405 with empty body"1953 ],1954 "_fragment": "generated/fragments/errors/xai-errors.json"1955 },1956 {1957 "provider": "xai",1958 "http_status": 415,1959 "type": "unsupported-media-type",1960 "code": null,1961 "category": "client",1962 "message_semantics": "Wrong Content-Type on a POST endpoint.",1963 "retryable": false,1964 "recommended_action": "Send application/json (or multipart/form-data where required).",1965 "source": "https://docs.x.ai/developers/debugging",1966 "observed_live": false,1967 "live_examples": [],1968 "_fragment": "generated/fragments/errors/xai-errors.json"1969 },1970 {1971 "provider": "xai",1972 "http_status": 422,1973 "type": "unprocessable-entity",1974 "code": null,1975 "category": "client",1976 "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.",1977 "retryable": false,1978 "recommended_action": "Fix field types (message names the field, line and column).",1979 "source": "https://docs.x.ai/developers/debugging",1980 "observed_live": true,1981 "live_examples": [1982 "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\""1983 ],1984 "_fragment": "generated/fragments/errors/xai-errors.json"1985 },1986 {1987 "provider": "xai",1988 "http_status": 429,1989 "type": "too-many-requests",1990 "code": "resource-exhausted (gRPC RESOURCE_EXHAUSTED)",1991 "category": "rate_limit",1992 "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).",1993 "retryable": true,1994 "backoff": "exponential (docs example: 2**attempt seconds, 5 retries); no Retry-After documented",1995 "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).",1996 "source": "https://docs.x.ai/developers/rate-limits",1997 "observed_live": false,1998 "live_examples": [],1999 "_fragment": "generated/fragments/errors/xai-errors.json"2000 },2001 {2002 "provider": "xai",2003 "http_status": 500,2004 "type": "internal",2005 "code": null,2006 "category": "server",2007 "message_semantics": "Server-side failure (not enumerated in docs; check https://status.x.ai and the RSS feed https://status.x.ai/feed.xml).",2008 "retryable": true,2009 "backoff": "exponential with jitter",2010 "recommended_action": "Retry; report persistent failures to support@x.ai with x-request-id.",2011 "source": "https://docs.x.ai/developers/debugging",2012 "observed_live": false,2013 "live_examples": [],2014 "_fragment": "generated/fragments/errors/xai-errors.json"2015 },2016 {2017 "provider": "xai",2018 "http_status": 202,2019 "type": "accepted (not an error)",2020 "code": null,2021 "category": "async",2022 "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.",2023 "retryable": true,2024 "recommended_action": "Poll with backoff.",2025 "source": "https://docs.x.ai/developers/advanced-api-usage/deferred-chat-completions",2026 "observed_live": false,2027 "live_examples": [],2028 "_fragment": "generated/fragments/errors/xai-errors.json"2029 },2030 {2031 "provider": "xai",2032 "http_status": 200,2033 "type": "usage-guideline-violation (billing event, not an HTTP error)",2034 "code": null,2035 "category": "policy",2036 "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.",2037 "retryable": false,2038 "recommended_action": "Review content policy.",2039 "source": "https://docs.x.ai/developers/pricing",2040 "observed_live": false,2041 "live_examples": [],2042 "_fragment": "generated/fragments/errors/xai-errors.json"2043 },2044 {2045 "provider": "xai",2046 "http_status": null,2047 "type": "grpc-status-mapping",2048 "code": "gRPC codes",2049 "category": "reference",2050 "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).",2051 "retryable": null,2052 "recommended_action": "In xai-sdk, catch grpc.RpcError and inspect e.code().",2053 "source": "https://docs.x.ai/developers/rate-limits",2054 "observed_live": true,2055 "live_examples": [2056 "management-api 401 body {\"code\": 16, \"message\": \"Invalid bearer token…\", \"details\": []}"2057 ],2058 "_fragment": "generated/fragments/errors/xai-errors.json"2059 }2060]