{ "checked_on": "2026-09-28", "description": "Versioned public error knowledge base used by GAIP Integration Repair: HTTP (RFC 9110, RFC 6585, RFC 9457), JSON-RPC 2.0, A2A 1.0, MCP 2025-11-25 and the published API errors of OpenAI, Anthropic and Google Gemini.", "entries": [ { "checked_on": "2026-09-28", "code": "400", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Read the response body; RFC 9457 problem details (type/title/detail) usually name the offending field.", "Validate the request against the supplier's published schema.", "Resend once corrected." ], "http_status": 400, "id": "http.400", "likely_owner": "caller", "meaning": "The server cannot or will not process the request because of a client error (malformed syntax, invalid framing or content).", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.1", "type": "Bad Request" }, { "checked_on": "2026-09-28", "code": "401", "default_for_status": true, "diagnosis": "AUTH_REQUIRED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Read WWW-Authenticate for the expected scheme (and resource_metadata for OAuth-protected MCP servers).", "Obtain or refresh a credential through the documented flow.", "Retry once; a second 401 means the credential is wrong or revoked." ], "http_status": 401, "id": "http.401", "likely_owner": "caller", "meaning": "The request lacks valid authentication credentials for the target resource; the response carries WWW-Authenticate.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.2", "type": "Unauthorized" }, { "checked_on": "2026-09-28", "code": "402", "default_for_status": true, "diagnosis": "BILLING_REQUIRED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Check the account's billing status and credit balance with the supplier.", "Do not retry until billing is resolved." ], "http_status": 402, "id": "http.402", "likely_owner": "caller", "meaning": "Reserved by HTTP; APIs use it for exhausted prepaid credit or billing problems.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.3", "type": "Payment Required" }, { "checked_on": "2026-09-28", "code": "403", "default_for_status": true, "diagnosis": "FORBIDDEN", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Compare token scopes with those the operation requires.", "Check plan, region and IP allow-lists.", "Ask the supplier to grant the permission; do not retry until granted." ], "http_status": 403, "id": "http.403", "likely_owner": "caller", "meaning": "The server understood the request but refuses to fulfil it; re-authenticating will not help.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.4", "type": "Forbidden" }, { "checked_on": "2026-09-28", "code": "404", "default_for_status": true, "diagnosis": "NOT_FOUND", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Re-read the supplier's current card or spec for the live URL.", "Check base-path versioning and resource ids.", "Report to the supplier if the URL is still published." ], "http_status": 404, "id": "http.404", "likely_owner": "caller", "meaning": "The origin server did not find a current representation for the target resource.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.5", "type": "Not Found" }, { "checked_on": "2026-09-28", "code": "405", "default_for_status": true, "diagnosis": "METHOD_NOT_ALLOWED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Read the Allow header.", "Use POST for JSON-RPC endpoints; check a redirect did not turn POST into GET.", "Resend with a permitted method." ], "http_status": 405, "id": "http.405", "likely_owner": "caller", "meaning": "The method is known but not supported by the target resource; the Allow header lists valid methods.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.6", "type": "Method Not Allowed" }, { "checked_on": "2026-09-28", "code": "406", "default_for_status": true, "diagnosis": "NOT_ACCEPTABLE", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Check the Accept header; MCP Streamable HTTP requires both application/json and text/event-stream on POST.", "Resend with an acceptable media type." ], "http_status": 406, "id": "http.406", "likely_owner": "caller", "meaning": "No representation matches the request's Accept/Accept-* headers.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.7", "type": "Not Acceptable" }, { "checked_on": "2026-09-28", "code": "407", "default_for_status": true, "diagnosis": "AUTH_REQUIRED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "This is the caller's egress proxy, not the supplier: configure proxy credentials.", "Retry once after the proxy accepts the connection." ], "http_status": 407, "id": "http.407", "likely_owner": "caller", "meaning": "A proxy between caller and supplier requires the caller to authenticate (Proxy-Authenticate header).", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.8", "type": "Proxy Authentication Required" }, { "checked_on": "2026-09-28", "code": "408", "default_for_status": true, "diagnosis": "REQUEST_TIMEOUT", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Retry on a fresh connection.", "Reduce or stream the request body." ], "http_status": 408, "id": "http.408", "likely_owner": "network", "meaning": "The server did not receive a complete request within the time it was prepared to wait.", "provider": "HTTP", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.9", "type": "Request Timeout" }, { "checked_on": "2026-09-28", "code": "409", "default_for_status": true, "diagnosis": "CONFLICT", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Fetch current state.", "If this was a retried create, check the first attempt did not succeed.", "Rebase on the current version (If-Match) and resend once." ], "http_status": 409, "id": "http.409", "likely_owner": "caller", "meaning": "The request conflicts with the current state of the target resource.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.10", "type": "Conflict" }, { "checked_on": "2026-09-28", "code": "410", "default_for_status": true, "diagnosis": "GONE", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Stop calling this URL.", "Find the replacement in the supplier's current card/spec or changelog (run Supplier Watch)." ], "http_status": 410, "id": "http.410", "likely_owner": "caller", "meaning": "The resource is no longer available at the origin and this is likely permanent.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.11", "type": "Gone" }, { "checked_on": "2026-09-28", "code": "411", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Send Content-Length (or ensure the client does not strip it).", "Resend once." ], "http_status": 411, "id": "http.411", "likely_owner": "caller", "meaning": "The server refuses the request without a defined Content-Length.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.12", "type": "Length Required" }, { "checked_on": "2026-09-28", "code": "412", "default_for_status": true, "diagnosis": "PRECONDITION_FAILED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Re-read the resource to obtain the current ETag.", "Reapply the change and resend once." ], "http_status": 412, "id": "http.412", "likely_owner": "caller", "meaning": "A condition in the request headers (If-Match, If-Unmodified-Since) evaluated to false.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.13", "type": "Precondition Failed" }, { "checked_on": "2026-09-28", "code": "413", "default_for_status": true, "diagnosis": "PAYLOAD_TOO_LARGE", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Find the documented size limit.", "Send files by reference or split the batch." ], "http_status": 413, "id": "http.413", "likely_owner": "caller", "meaning": "The request content is larger than the server is willing or able to process.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.14", "type": "Content Too Large" }, { "checked_on": "2026-09-28", "code": "414", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Move large parameters into a POST body.", "Resend once." ], "http_status": 414, "id": "http.414", "likely_owner": "caller", "meaning": "The target URI is longer than the server is willing to interpret.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.15", "type": "URI Too Long" }, { "checked_on": "2026-09-28", "code": "415", "default_for_status": true, "diagnosis": "UNSUPPORTED_MEDIA_TYPE", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Send Content-Type: application/json for JSON APIs.", "Check declared input modes/media types." ], "http_status": 415, "id": "http.415", "likely_owner": "caller", "meaning": "The content is in a format not supported by the target resource for this method.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.16", "type": "Unsupported Media Type" }, { "checked_on": "2026-09-28", "code": "416", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Re-read the resource length and request a valid range." ], "http_status": 416, "id": "http.416", "likely_owner": "caller", "meaning": "None of the requested ranges overlap the selected representation.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.17", "type": "Range Not Satisfiable" }, { "checked_on": "2026-09-28", "code": "417", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Remove 'Expect: 100-continue' or send the body directly.", "Resend once." ], "http_status": 417, "id": "http.417", "likely_owner": "caller", "meaning": "The Expect request header could not be met.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.18", "type": "Expectation Failed" }, { "checked_on": "2026-09-28", "code": "421", "default_for_status": true, "diagnosis": null, "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Open a new connection for this host (do not reuse a coalesced HTTP/2 connection).", "Check SNI/Host headers match the target." ], "http_status": 421, "id": "http.421", "likely_owner": "network", "meaning": "The request was directed at a server unable to produce a response for this scheme and authority (often connection reuse across hosts).", "provider": "HTTP", "retry_guidance": "Retry once on a new connection to the correct host.", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.20", "type": "Misdirected Request" }, { "checked_on": "2026-09-28", "code": "422", "default_for_status": true, "diagnosis": "VALIDATION_FAILED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Read the validation errors (field path and rule).", "Compare against the current schema; a release may have added a required field.", "Fix and resend once." ], "http_status": 422, "id": "http.422", "likely_owner": "caller", "meaning": "The content type and syntax are understood but the instructions cannot be processed (validation failure).", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.21", "type": "Unprocessable Content" }, { "checked_on": "2026-09-28", "code": "426", "default_for_status": true, "diagnosis": "UNSUPPORTED_PROTOCOL", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Read the Upgrade header (for example TLS/1.2 or HTTP/2).", "Upgrade the client transport and resend." ], "http_status": 426, "id": "http.426", "likely_owner": "caller", "meaning": "The server refuses to perform the request using the current protocol (Upgrade header names the required one).", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.5.22", "type": "Upgrade Required" }, { "checked_on": "2026-09-28", "code": "500", "default_for_status": true, "diagnosis": "SUPPLIER_SERVER_ERROR", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Retry idempotent calls with backoff.", "Report to the supplier with the request id if it persists." ], "http_status": 500, "id": "http.500", "likely_owner": "supplier", "meaning": "The server encountered an unexpected condition that prevented it from fulfilling the request.", "provider": "HTTP", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.1", "type": "Internal Server Error" }, { "checked_on": "2026-09-28", "code": "501", "default_for_status": true, "diagnosis": "NOT_IMPLEMENTED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Use an operation the supplier declares.", "Ask the supplier whether support is planned." ], "http_status": 501, "id": "http.501", "likely_owner": "supplier", "meaning": "The server does not support the functionality required to fulfil the request.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.2", "type": "Not Implemented" }, { "checked_on": "2026-09-28", "code": "502", "default_for_status": true, "diagnosis": "BAD_GATEWAY", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Retry with backoff.", "Check the supplier status page; report persistent 502s with Server/Via headers." ], "http_status": 502, "id": "http.502", "likely_owner": "supplier", "meaning": "A gateway or proxy received an invalid response from the upstream server.", "provider": "HTTP", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.3", "type": "Bad Gateway" }, { "checked_on": "2026-09-28", "code": "503", "default_for_status": true, "diagnosis": "SERVICE_UNAVAILABLE", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Honour Retry-After.", "Check the status page.", "Fail over for time-critical work." ], "http_status": 503, "id": "http.503", "likely_owner": "supplier", "meaning": "The server is temporarily unable to handle the request (overload or maintenance); Retry-After may say when to retry.", "provider": "HTTP", "retry_guidance": "Honour Retry-After when present; otherwise back off exponentially (1 s base, 30 s cap, 3 attempts).", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.4", "type": "Service Unavailable" }, { "checked_on": "2026-09-28", "code": "504", "default_for_status": true, "diagnosis": "GATEWAY_TIMEOUT", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Check for completion via a status endpoint.", "Retry once with an idempotency key.", "Use asynchronous submit-and-poll for long work." ], "http_status": 504, "id": "http.504", "likely_owner": "supplier", "meaning": "A gateway did not receive a timely response from the upstream server; the work may still have completed.", "provider": "HTTP", "retry_guidance": "Check whether the first attempt took effect, then retry once with an idempotency key and a longer timeout.", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.5", "type": "Gateway Timeout" }, { "checked_on": "2026-09-28", "code": "505", "default_for_status": true, "diagnosis": "UNSUPPORTED_PROTOCOL", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Configure the client for HTTP/1.1 or HTTP/2 as the supplier supports." ], "http_status": 505, "id": "http.505", "likely_owner": "caller", "meaning": "The server does not support the major HTTP version used in the request.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9110.html#section-15.6.6", "type": "HTTP Version Not Supported" }, { "checked_on": "2026-09-28", "code": "425", "default_for_status": true, "diagnosis": null, "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Disable 0-RTT early data for this request.", "Retry once." ], "http_status": 425, "id": "http.425", "likely_owner": "network", "meaning": "The server is unwilling to process a request that might be replayed (TLS 1.3 early data).", "provider": "HTTP", "retry_guidance": "Retry once after the TLS handshake completes (do not send as early data).", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc8470.html#section-5.2", "type": "Too Early" }, { "checked_on": "2026-09-28", "code": "428", "default_for_status": true, "diagnosis": "PRECONDITION_FAILED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Fetch the resource ETag.", "Resend with If-Match." ], "http_status": 428, "id": "http.428", "likely_owner": "caller", "meaning": "The origin requires the request to be conditional (If-Match) to prevent lost updates.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc6585.html#section-3", "type": "Precondition Required" }, { "checked_on": "2026-09-28", "code": "429", "default_for_status": true, "diagnosis": "RATE_LIMITED", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Stop sending and honour Retry-After.", "Read RateLimit-* headers for the window.", "Add client-side throttling; request more quota if sustained." ], "http_status": 429, "id": "http.429", "likely_owner": "caller", "meaning": "The caller sent too many requests in a given time (rate limiting); Retry-After may say how long to wait.", "provider": "HTTP", "retry_guidance": "Honour Retry-After when present (give up automatically if it exceeds 300 s); otherwise back off exponentially with jitter from 2 s (cap 60 s), at most 4 attempts.", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc6585.html#section-4", "type": "Too Many Requests" }, { "checked_on": "2026-09-28", "code": "431", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Remove oversized cookies or headers (large tokens, trace baggage).", "Resend once." ], "http_status": 431, "id": "http.431", "likely_owner": "caller", "meaning": "A header field, or all headers together, are too large.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc6585.html#section-5", "type": "Request Header Fields Too Large" }, { "checked_on": "2026-09-28", "code": "451", "default_for_status": true, "diagnosis": "FORBIDDEN", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Do not retry or route around the restriction.", "Contact the supplier for the applicable jurisdiction." ], "http_status": 451, "id": "http.451", "likely_owner": "supplier", "meaning": "Access is denied as a consequence of a legal demand.", "provider": "HTTP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc7725.html#section-3", "type": "Unavailable For Legal Reasons" }, { "checked_on": "2026-09-28", "code": "507", "default_for_status": true, "diagnosis": "SUPPLIER_SERVER_ERROR", "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Retry later with backoff.", "Report to the supplier if persistent." ], "http_status": 507, "id": "http.507", "likely_owner": "supplier", "meaning": "The server cannot store the representation needed to complete the request.", "provider": "HTTP", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://www.rfc-editor.org/rfc/rfc4918.html#section-11.5", "type": "Insufficient Storage" }, { "checked_on": "2026-09-28", "code": "511", "default_for_status": true, "diagnosis": null, "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "The caller's network, not the supplier, is intercepting: complete network sign-in or use another network.", "Retry once." ], "http_status": 511, "id": "http.511", "likely_owner": "network", "meaning": "An intercepting network (captive portal) requires authentication before access.", "provider": "HTTP", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc6585.html#section-6", "type": "Network Authentication Required" }, { "checked_on": "2026-09-28", "code": "application/problem+json", "diagnosis": null, "evidence": "SPEC", "family": "HTTP", "fix_steps": [ "Read 'type' and look it up in the supplier's documentation; it identifies the problem class.", "Use 'detail' for the occurrence-specific explanation and 'instance' as the reference to report.", "Treat extension members (for example 'errors' or 'invalid-params') as the field-level list to fix." ], "id": "http.problem_details", "likely_owner": "caller", "meaning": "RFC 9457 Problem Details body: 'type' (URI identifying the problem type, default about:blank), 'title', 'status', 'detail' and 'instance' describe the error in a machine-readable way.", "message_patterns": [ "application/problem\\+json", "about:blank" ], "provider": "HTTP", "requires_pattern": true, "retry_guidance": "Follow the retry guidance for the HTTP status in 'status'.", "retryable": false, "spec_url": "https://www.rfc-editor.org/rfc/rfc9457.html", "type": "Problem Details for HTTP APIs" }, { "checked_on": "2026-09-28", "code": "-32700", "diagnosis": "JSONRPC_PARSE_ERROR", "evidence": "SPEC", "family": "JSON_RPC", "fix_steps": [ "Serialise with a JSON library and send UTF-8.", "Check a proxy did not truncate the body." ], "id": "jsonrpc.32700", "jsonrpc_code": -32700, "likely_owner": "caller", "meaning": "Invalid JSON was received by the server.", "provider": "JSON_RPC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.jsonrpc.org/specification#error_object", "type": "Parse error" }, { "checked_on": "2026-09-28", "code": "-32600", "diagnosis": "JSONRPC_INVALID_REQUEST", "evidence": "SPEC", "family": "JSON_RPC", "fix_steps": [ "Send jsonrpc: \"2.0\", a string method, an id and params as an object or array." ], "id": "jsonrpc.32600", "jsonrpc_code": -32600, "likely_owner": "caller", "meaning": "The JSON sent is not a valid Request object.", "provider": "JSON_RPC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.jsonrpc.org/specification#error_object", "type": "Invalid Request" }, { "checked_on": "2026-09-28", "code": "-32601", "diagnosis": "JSONRPC_METHOD_NOT_FOUND", "evidence": "SPEC", "family": "JSON_RPC", "fix_steps": [ "Check the method name against the protocol version the server speaks.", "Call a discovery method (tools/list or the agent card)." ], "id": "jsonrpc.32601", "jsonrpc_code": -32601, "likely_owner": "caller", "meaning": "The method does not exist or is not available.", "provider": "JSON_RPC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.jsonrpc.org/specification#error_object", "type": "Method not found" }, { "checked_on": "2026-09-28", "code": "-32602", "diagnosis": "JSONRPC_INVALID_PARAMS", "evidence": "SPEC", "family": "JSON_RPC", "fix_steps": [ "Read error.data for the failing field.", "Match params to the declared schema." ], "id": "jsonrpc.32602", "jsonrpc_code": -32602, "likely_owner": "caller", "meaning": "Invalid method parameter(s).", "provider": "JSON_RPC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://www.jsonrpc.org/specification#error_object", "type": "Invalid params" }, { "checked_on": "2026-09-28", "code": "-32603", "diagnosis": "JSONRPC_INTERNAL_ERROR", "evidence": "SPEC", "family": "JSON_RPC", "fix_steps": [ "Retry idempotent calls with backoff.", "Report with the JSON-RPC id and timestamp." ], "id": "jsonrpc.32603", "jsonrpc_code": -32603, "likely_owner": "supplier", "meaning": "Internal JSON-RPC error.", "provider": "JSON_RPC", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://www.jsonrpc.org/specification#error_object", "type": "Internal error" }, { "checked_on": "2026-09-28", "code": "-32000..-32099", "diagnosis": null, "evidence": "SPEC", "family": "JSON_RPC", "fix_steps": [ "Check the protocol (A2A, MCP) and look up the specific code.", "Read error.message and error.data." ], "id": "jsonrpc.server_error_range", "likely_owner": "supplier", "meaning": "Reserved for implementation-defined server errors; protocols such as A2A and MCP assign specific meanings inside this range.", "provider": "JSON_RPC", "retry_guidance": "Look the code up for the specific protocol before retrying.", "retryable": false, "spec_url": "https://www.jsonrpc.org/specification#error_object", "type": "Server error" }, { "aliases": [ "TaskNotFoundError" ], "checked_on": "2026-09-28", "code": "-32001", "diagnosis": "A2A_TASK_NOT_FOUND", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Use the exact task id returned by SendMessage.", "Poll within the agent's retention window; resubmit if expired." ], "grpc_status": "NOT_FOUND", "http_status": 404, "id": "a2a.TaskNotFoundError", "jsonrpc_code": -32001, "likely_owner": "caller", "meaning": "The task id does not correspond to an existing or accessible task (invalid, expired or purged).", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "TaskNotFoundError" }, { "aliases": [ "TaskNotCancelableError" ], "checked_on": "2026-09-28", "code": "-32002", "diagnosis": "A2A_TASK_NOT_CANCELABLE", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Call GetTask to read the final state instead of cancelling." ], "grpc_status": "FAILED_PRECONDITION", "http_status": 400, "id": "a2a.TaskNotCancelableError", "jsonrpc_code": -32002, "likely_owner": "caller", "meaning": "The task cannot be canceled (already COMPLETED, FAILED, CANCELED or REJECTED, or cancel unsupported).", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "TaskNotCancelableError" }, { "aliases": [ "PushNotificationNotSupportedError" ], "checked_on": "2026-09-28", "code": "-32003", "diagnosis": "A2A_PUSH_NOT_SUPPORTED", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Check capabilities.pushNotifications.", "Poll with GetTask or stream instead." ], "grpc_status": "FAILED_PRECONDITION", "http_status": 400, "id": "a2a.PushNotificationNotSupportedError", "jsonrpc_code": -32003, "likely_owner": "caller", "meaning": "The agent does not support push notifications.", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "PushNotificationNotSupportedError" }, { "aliases": [ "UnsupportedOperationError" ], "checked_on": "2026-09-28", "code": "-32004", "diagnosis": "A2A_UNSUPPORTED_OPERATION", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Compare the call with the agent card capabilities.", "Use a supported alternative (SendMessage instead of streaming)." ], "grpc_status": "FAILED_PRECONDITION", "http_status": 400, "id": "a2a.UnsupportedOperationError", "jsonrpc_code": -32004, "likely_owner": "caller", "meaning": "The requested operation or an aspect of it is not supported by this agent.", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "UnsupportedOperationError" }, { "aliases": [ "ContentTypeNotSupportedError" ], "checked_on": "2026-09-28", "code": "-32005", "diagnosis": "A2A_CONTENT_TYPE_NOT_SUPPORTED", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Read the skill inputModes / defaultInputModes.", "Convert the part to a supported media type." ], "grpc_status": "INVALID_ARGUMENT", "http_status": 400, "id": "a2a.ContentTypeNotSupportedError", "jsonrpc_code": -32005, "likely_owner": "caller", "meaning": "A media type in the message parts or artifact is not supported by the agent or skill.", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "ContentTypeNotSupportedError" }, { "aliases": [ "InvalidAgentResponseError" ], "checked_on": "2026-09-28", "code": "-32006", "diagnosis": "A2A_INVALID_AGENT_RESPONSE", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Capture the raw response.", "Report it to the supplier as a protocol defect." ], "grpc_status": "INTERNAL", "http_status": 500, "id": "a2a.InvalidAgentResponseError", "jsonrpc_code": -32006, "likely_owner": "supplier", "meaning": "The agent returned a response that does not conform to the specification.", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Retry once; a repeated invalid response is a supplier defect.", "retryable": true, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "InvalidAgentResponseError" }, { "aliases": [ "ExtendedAgentCardNotConfiguredError" ], "checked_on": "2026-09-28", "code": "-32007", "diagnosis": "A2A_EXTENDED_CARD_NOT_CONFIGURED", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Use the public agent card.", "Only request the extended card when capabilities.extendedAgentCard is true." ], "grpc_status": "FAILED_PRECONDITION", "http_status": 400, "id": "a2a.ExtendedAgentCardNotConfiguredError", "jsonrpc_code": -32007, "likely_owner": "caller", "meaning": "The agent has no extended agent card configured although one was requested.", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "ExtendedAgentCardNotConfiguredError" }, { "aliases": [ "ExtensionSupportRequiredError" ], "checked_on": "2026-09-28", "code": "-32008", "diagnosis": "A2A_EXTENSION_SUPPORT_REQUIRED", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Read capabilities.extensions for entries with required: true.", "Implement and declare the extension, then retry once." ], "grpc_status": "FAILED_PRECONDITION", "http_status": 400, "id": "a2a.ExtensionSupportRequiredError", "jsonrpc_code": -32008, "likely_owner": "caller", "meaning": "The agent requires an extension marked required: true in its card, and the client did not declare support.", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "ExtensionSupportRequiredError" }, { "aliases": [ "VersionNotSupportedError" ], "checked_on": "2026-09-28", "code": "-32009", "diagnosis": "A2A_VERSION_NOT_SUPPORTED", "evidence": "SPEC", "family": "A2A", "fix_steps": [ "Read supportedInterfaces[].protocolVersion on the agent card.", "Send a version the agent supports and retry once." ], "grpc_status": "FAILED_PRECONDITION", "http_status": 400, "id": "a2a.VersionNotSupportedError", "jsonrpc_code": -32009, "likely_owner": "caller", "meaning": "The A2A protocol version specified in the request is not supported by the agent.", "note": "JSON-RPC, gRPC and HTTP+JSON mappings per the A2A 1.0 error code mappings table.", "protocol": "A2A", "provider": "A2A", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://a2a-protocol.org/latest/specification/#332-error-handling", "type": "VersionNotSupportedError" }, { "checked_on": "2026-09-28", "code": "-32002", "diagnosis": "MCP_RESOURCE_NOT_FOUND", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Call resources/list or resources/templates/list and use an exact URI." ], "id": "mcp.resource_not_found", "jsonrpc_code": -32002, "likely_owner": "caller", "meaning": "The requested resource URI is not available on this MCP server.", "protocol": "MCP", "provider": "MCP", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/server/resources#error-handling", "type": "Resource not found" }, { "aliases": [ "URL_ELICITATION_REQUIRED", "URLElicitationRequiredError" ], "checked_on": "2026-09-28", "code": "-32042", "diagnosis": "MCP_URL_ELICITATION_REQUIRED", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Show the user the elicitation URL and domain and obtain consent; never pre-fetch it.", "After completion, retry the original request once." ], "id": "mcp.url_elicitation_required", "jsonrpc_code": -32042, "likely_owner": "caller", "meaning": "URLElicitationRequiredError: the request cannot be processed until the user completes the URL-mode elicitation(s) listed in error.data.elicitations.", "protocol": "MCP", "provider": "MCP", "retry_guidance": "Retry the original request once, after the user has completed the elicitation (or notifications/elicitation/complete arrives).", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#error-handling", "type": "URLElicitationRequiredError" }, { "checked_on": "2026-09-28", "code": "-32602", "diagnosis": "MCP_TOOL_NOT_FOUND", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Call tools/list and use an exact tool name.", "Validate arguments against the tool's inputSchema." ], "id": "mcp.unknown_tool", "jsonrpc_code": -32602, "likely_owner": "caller", "meaning": "Protocol error for an unknown tool name or a malformed tools/call request.", "message_patterns": [ "unknown tool", "tool .{0,60}not found", "no such tool" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling", "type": "Unknown tool" }, { "checked_on": "2026-09-28", "code": "-32602", "diagnosis": "PROTOCOL_VERSION_MISMATCH", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Read error.data.supported.", "Initialize again with a supported version." ], "id": "mcp.unsupported_protocol_version", "jsonrpc_code": -32602, "likely_owner": "caller", "meaning": "The server does not support the protocolVersion requested in initialize (error.data lists supported and requested versions).", "message_patterns": [ "unsupported protocol version" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#error-handling", "type": "Unsupported protocol version" }, { "aliases": [ "isError" ], "checked_on": "2026-09-28", "code": "isError", "diagnosis": "MCP_TOOL_ERROR", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Read result.content[].text for the actionable message.", "Adjust the arguments and call once more." ], "id": "mcp.tool_execution_error", "likely_owner": "caller", "meaning": "Tool execution error: the call succeeded at protocol level but result.isError is true (API failure, input validation or business-logic error).", "message_patterns": [ "is_?error[\\\"': ]+true", "\\bisError\\b" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/server/tools#error-handling", "type": "Tool execution error" }, { "checked_on": "2026-09-28", "code": "HTTP 400 MCP-Protocol-Version", "diagnosis": "PROTOCOL_VERSION_MISMATCH", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Send MCP-Protocol-Version with the version negotiated during initialize.", "Retry once." ], "http_status": 400, "id": "mcp.http_bad_protocol_version_header", "likely_owner": "caller", "meaning": "Streamable HTTP: the server MUST answer 400 when the MCP-Protocol-Version header is invalid or unsupported.", "message_patterns": [ "mcp-protocol-version", "unsupported protocol version", "invalid protocol version" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header" }, { "checked_on": "2026-09-28", "code": "HTTP 400 MCP-Session-Id missing", "diagnosis": "BAD_REQUEST", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Store the MCP-Session-Id returned with InitializeResult.", "Send it on every subsequent request." ], "http_status": 400, "id": "mcp.http_session_required", "likely_owner": "caller", "meaning": "Streamable HTTP: servers that require a session SHOULD answer 400 to requests (other than initialize) without MCP-Session-Id.", "message_patterns": [ "session[- ]id.{0,20}(required|missing)", "missing (mcp-)?session", "no valid session" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management" }, { "checked_on": "2026-09-28", "code": "HTTP 404 MCP-Session-Id", "diagnosis": "MCP_SESSION_EXPIRED", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Send a new InitializeRequest without MCP-Session-Id.", "Use the new session id and retry the request once." ], "http_status": 404, "id": "mcp.http_session_expired", "likely_owner": "caller", "meaning": "Streamable HTTP: the server terminated the session; requests carrying that MCP-Session-Id get 404 and the client MUST start a new session.", "message_patterns": [ "session (not found|expired|terminated|unknown)", "mcp-session-id", "invalid session" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Re-initialize (new InitializeRequest without a session id), then retry the request once.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management" }, { "checked_on": "2026-09-28", "code": "HTTP 405 GET", "diagnosis": "METHOD_NOT_ALLOWED", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Use POST for requests; do not rely on a standalone GET stream.", "Poll or use per-request SSE responses instead." ], "http_status": 405, "id": "mcp.http_get_no_sse", "likely_owner": "caller", "meaning": "Streamable HTTP: the server does not offer a server-initiated SSE stream at this endpoint and answers GET with 405.", "message_patterns": [ "\\bget\\b.{0,40}(not allowed|not supported)", "sse.{0,30}not (supported|offered)" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server" }, { "checked_on": "2026-09-28", "code": "HTTP 403 Origin", "diagnosis": "FORBIDDEN", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Call from a server-side client (no browser Origin) or an origin the supplier allows." ], "http_status": 403, "id": "mcp.http_invalid_origin", "likely_owner": "caller", "meaning": "Streamable HTTP: the server MUST answer 403 when an Origin header is present and invalid (DNS-rebinding protection).", "message_patterns": [ "\\borigin\\b.{0,40}(invalid|not allowed|forbidden)", "invalid origin" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#security-warning" }, { "checked_on": "2026-09-28", "code": "HTTP 401 WWW-Authenticate resource_metadata", "diagnosis": "AUTH_REQUIRED", "evidence": "SPEC", "family": "MCP", "fix_steps": [ "Read resource_metadata from WWW-Authenticate and fetch the Protected Resource Metadata.", "Complete the OAuth flow with the listed authorization server (outside this route) and send the bearer token.", "Retry once." ], "http_status": 401, "id": "mcp.http_unauthorized", "likely_owner": "caller", "meaning": "MCP authorization: the protected server answers 401 with WWW-Authenticate pointing to its OAuth Protected Resource Metadata.", "message_patterns": [ "resource_metadata", "oauth-protected-resource" ], "protocol": "MCP", "provider": "MCP", "requires_pattern": true, "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization" }, { "aliases": [ "ConnectionClosed" ], "checked_on": "2026-09-28", "code": "-32000", "diagnosis": "CONNECTION_RESET", "evidence": "SDK_SOURCE", "family": "MCP", "fix_steps": [ "Reconnect and re-initialize the session.", "For SSE streams, resume with Last-Event-ID where supported." ], "id": "mcp.sdk_connection_closed", "jsonrpc_code": -32000, "likely_owner": "network", "meaning": "SDK-defined ConnectionClosed: the transport closed before a response arrived.", "note": "Defined by the official MCP SDKs (ErrorCode.ConnectionClosed), not by the core specification.", "protocol": "MCP", "provider": "MCP", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/types.ts", "type": "ConnectionClosed" }, { "aliases": [ "RequestTimeout" ], "checked_on": "2026-09-28", "code": "-32001", "diagnosis": "TIMEOUT", "evidence": "SDK_SOURCE", "family": "MCP", "fix_steps": [ "Raise the per-request timeout or reset it on progress notifications.", "Retry once." ], "id": "mcp.sdk_request_timeout", "jsonrpc_code": -32001, "likely_owner": "network", "meaning": "SDK-defined RequestTimeout: no response arrived within the client's request timeout.", "note": "Defined by the official MCP SDKs (ErrorCode.RequestTimeout); in A2A the same number means TaskNotFoundError.", "protocol": "MCP", "provider": "MCP", "retry_guidance": "Check whether the request took effect, then retry once with a longer timeout; use progress notifications for long tools.", "retryable": true, "spec_url": "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/types.ts", "type": "RequestTimeout" }, { "checked_on": "2026-09-28", "code": "invalid_api_key", "default_for_status": true, "diagnosis": "AUTH_REQUIRED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check the key and the OpenAI-Organization/OpenAI-Project headers.", "Clear cached credentials or generate a new key.", "Retry once." ], "http_status": 401, "id": "openai.invalid_api_key", "likely_owner": "caller", "meaning": "Invalid Authentication / Incorrect API key provided: the key is wrong, revoked or for another organization/project.", "message_patterns": [ "incorrect api key provided", "invalid authentication" ], "provider": "OPENAI", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "invalid_request_error" }, { "checked_on": "2026-09-28", "code": "401 organization membership", "diagnosis": "AUTH_REQUIRED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Create or join an organization in the account settings.", "Retry after membership is active." ], "http_status": 401, "id": "openai.no_organization", "likely_owner": "caller", "meaning": "You must be a member of an organization to use the API.", "message_patterns": [ "must be a member of an organization" ], "provider": "OPENAI", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "401 IP not authorized", "diagnosis": "FORBIDDEN", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Send from an allow-listed IP or update the allowlist." ], "http_status": 401, "id": "openai.ip_not_authorized", "likely_owner": "caller", "meaning": "The request IP does not match the project's IP allowlist.", "message_patterns": [ "ip.{0,20}not authorized" ], "provider": "OPENAI", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "unsupported_country_region_territory", "default_for_status": true, "diagnosis": "FORBIDDEN", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check the supported countries list; do not route around the restriction." ], "http_status": 403, "id": "openai.unsupported_region", "likely_owner": "caller", "meaning": "Country, region, or territory not supported.", "message_patterns": [ "country, region, or territory not supported" ], "provider": "OPENAI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "model_not_found", "default_for_status": true, "diagnosis": "NOT_FOUND", "evidence": "OBSERVED_API_RESPONSE", "family": "LLM_PROVIDER", "fix_steps": [ "Check the model id against the models list available to the project.", "Use an available model and retry once." ], "http_status": 404, "id": "openai.model_not_found", "likely_owner": "caller", "meaning": "The model does not exist or the key has no access to it.", "message_patterns": [ "the model .{0,80} does not exist" ], "note": "Error code as returned in the API error object; the error-codes guide covers the 404 class via NotFoundError.", "provider": "OPENAI", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "invalid_request_error" }, { "checked_on": "2026-09-28", "code": "context_length_exceeded", "diagnosis": "CONTEXT_LENGTH_EXCEEDED", "evidence": "OBSERVED_API_RESPONSE", "family": "LLM_PROVIDER", "fix_steps": [ "Count tokens before sending and trim or summarise history.", "Lower max_output_tokens / max_tokens.", "Use a model with a larger context window." ], "http_status": 400, "id": "openai.context_length_exceeded", "likely_owner": "caller", "meaning": "The prompt plus requested output exceeds the model's maximum context length.", "message_patterns": [ "maximum context length is", "context_length_exceeded", "exceeds the context window" ], "note": "Returned as error.code in a 400 invalid_request_error body.", "provider": "OPENAI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "invalid_request_error" }, { "checked_on": "2026-09-28", "code": "invalid_request_error", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Read error.param and error.message.", "Fix the named parameter and resend once." ], "http_status": 400, "id": "openai.invalid_request", "likely_owner": "caller", "meaning": "The request is malformed or has missing/invalid parameters (error.param names the field).", "provider": "OPENAI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "invalid_request_error" }, { "checked_on": "2026-09-28", "code": "400 invalid service_tier", "diagnosis": "BAD_REQUEST", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Select an allowed service_tier or change project settings." ], "http_status": 400, "id": "openai.invalid_service_tier", "likely_owner": "caller", "meaning": "The requested service tier is not allowed for this project.", "message_patterns": [ "requested service tier is not allowed" ], "provider": "OPENAI", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "aliases": [ "tokens", "requests" ], "checked_on": "2026-09-28", "code": "rate_limit_exceeded", "default_for_status": true, "diagnosis": "RATE_LIMITED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Pace requests; honour Retry-After and x-ratelimit-* headers.", "Batch or queue requests; request a higher limit if sustained." ], "http_status": 429, "id": "openai.rate_limit_exceeded", "likely_owner": "caller", "meaning": "Rate limit reached for requests or tokens per minute.", "message_patterns": [ "rate limit reached for" ], "provider": "OPENAI", "retry_guidance": "Honour Retry-After when present (give up automatically if it exceeds 300 s); otherwise back off exponentially with jitter from 2 s (cap 60 s), at most 4 attempts.", "retryable": true, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "requests" }, { "checked_on": "2026-09-28", "code": "slow_down", "diagnosis": "RATE_LIMITED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Reduce request rate.", "Increase traffic gradually." ], "http_status": 429, "id": "openai.slow_down", "likely_owner": "caller", "meaning": "Request rate increased too quickly (type rate_limit_error).", "provider": "OPENAI", "retry_guidance": "Honour Retry-After; reduce the rate and ramp up gradually (the guide suggests at most 50% every 15 minutes at 1M TPM).", "retryable": true, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "rate_limit_error" }, { "checked_on": "2026-09-28", "code": "insufficient_quota", "diagnosis": "QUOTA_EXHAUSTED", "evidence": "OBSERVED_API_RESPONSE", "family": "LLM_PROVIDER", "fix_steps": [ "Check plan and billing details; add credit or raise the quota.", "Resume only after the limit is lifted." ], "http_status": 429, "id": "openai.insufficient_quota", "likely_owner": "caller", "meaning": "You exceeded your current quota: the plan/billing quota is exhausted.", "message_patterns": [ "exceeded your current quota" ], "note": "HTTP 429 but not a rate limit: do not back off and retry.", "provider": "OPENAI", "retry_guidance": "Not transient: retrying will keep failing until billing or limits change.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "credit_balance_exhausted", "diagnosis": "QUOTA_EXHAUSTED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Add credits in billing settings.", "Resume only after the limit is lifted." ], "http_status": 429, "id": "openai.credit_balance_exhausted", "likely_owner": "caller", "meaning": "Prepaid credit balance exhausted.", "provider": "OPENAI", "retry_guidance": "Not transient: retrying will keep failing until billing or limits change.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "organization_spend_limit_exceeded", "diagnosis": "QUOTA_EXHAUSTED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Increase or remove the organization spend limit.", "Resume only after the limit is lifted." ], "http_status": 429, "id": "openai.organization_spend_limit_exceeded", "likely_owner": "caller", "meaning": "Organization spend limit reached.", "provider": "OPENAI", "retry_guidance": "Not transient: retrying will keep failing until billing or limits change.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "project_spend_limit_exceeded", "diagnosis": "QUOTA_EXHAUSTED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Adjust the project spend limit.", "Resume only after the limit is lifted." ], "http_status": 429, "id": "openai.project_spend_limit_exceeded", "likely_owner": "caller", "meaning": "Project spend limit reached.", "provider": "OPENAI", "retry_guidance": "Not transient: retrying will keep failing until billing or limits change.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "organization_usage_limit_exceeded", "diagnosis": "QUOTA_EXHAUSTED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Request a higher approved usage limit or contact support.", "Resume only after the limit is lifted." ], "http_status": 429, "id": "openai.organization_usage_limit_exceeded", "likely_owner": "caller", "meaning": "Organization usage limit reached.", "provider": "OPENAI", "retry_guidance": "Not transient: retrying will keep failing until billing or limits change.", "retryable": false, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "checked_on": "2026-09-28", "code": "server_error", "default_for_status": true, "diagnosis": "SUPPLIER_SERVER_ERROR", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Retry after a brief wait.", "Check the status page if it persists." ], "http_status": 500, "id": "openai.server_error", "likely_owner": "supplier", "meaning": "Issue on OpenAI's servers while processing the request.", "provider": "OPENAI", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "server_error" }, { "checked_on": "2026-09-28", "code": "server_is_overloaded", "default_for_status": true, "diagnosis": "PROVIDER_OVERLOADED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Honour Retry-After and retry.", "Reduce concurrency during peaks." ], "http_status": 503, "id": "openai.server_is_overloaded", "likely_owner": "supplier", "meaning": "Model temporarily overloaded (type service_unavailable_error).", "message_patterns": [ "overloaded" ], "provider": "OPENAI", "retry_guidance": "Transient capacity problem: honour Retry-After if present, otherwise back off exponentially with jitter from 2 s (cap 60 s), at most 4 attempts; ramp traffic back gradually.", "retryable": true, "spec_url": "https://developers.openai.com/api/docs/guides/error-codes", "type": "service_unavailable_error" }, { "checked_on": "2026-09-28", "code": "invalid_request_error", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Read error.message for the offending field.", "Fix and resend once." ], "http_status": 400, "id": "anthropic.invalid_request_error", "likely_owner": "caller", "meaning": "There was an issue with the format or content of the request (also returned when a spend limit is reached).", "provider": "ANTHROPIC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "invalid_request_error" }, { "checked_on": "2026-09-28", "code": "authentication_error", "default_for_status": true, "diagnosis": "AUTH_REQUIRED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check the x-api-key header value.", "Create a new key if revoked; retry once." ], "http_status": 401, "id": "anthropic.authentication_error", "likely_owner": "caller", "meaning": "There is an issue with the API key (malformed, revoked or expired).", "provider": "ANTHROPIC", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "authentication_error" }, { "checked_on": "2026-09-28", "code": "billing_error", "default_for_status": true, "diagnosis": "BILLING_REQUIRED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Fix billing details in the console.", "Retry after billing is resolved." ], "http_status": 402, "id": "anthropic.billing_error", "likely_owner": "caller", "meaning": "There is an issue with billing or payment information.", "provider": "ANTHROPIC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "billing_error" }, { "checked_on": "2026-09-28", "code": "permission_error", "default_for_status": true, "diagnosis": "FORBIDDEN", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check workspace and key permissions for the model or feature." ], "http_status": 403, "id": "anthropic.permission_error", "likely_owner": "caller", "meaning": "The API key does not have permission to use the specified resource.", "provider": "ANTHROPIC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "permission_error" }, { "checked_on": "2026-09-28", "code": "not_found_error", "default_for_status": true, "diagnosis": "NOT_FOUND", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check the model id or resource id and endpoint path." ], "http_status": 404, "id": "anthropic.not_found_error", "likely_owner": "caller", "meaning": "The requested resource was not found.", "provider": "ANTHROPIC", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "not_found_error" }, { "checked_on": "2026-09-28", "code": "conflict_error", "default_for_status": true, "diagnosis": "CONFLICT", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Re-read the resource state and resend once." ], "http_status": 409, "id": "anthropic.conflict_error", "likely_owner": "caller", "meaning": "The request conflicts with the current state of the resource (concurrent modification or duplicate unique value).", "provider": "ANTHROPIC", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "conflict_error" }, { "checked_on": "2026-09-28", "code": "request_too_large", "default_for_status": true, "diagnosis": "PAYLOAD_TOO_LARGE", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Send large files via the Files API or by reference.", "Split the request." ], "http_status": 413, "id": "anthropic.request_too_large", "likely_owner": "caller", "meaning": "The request exceeds the maximum allowed number of bytes (32 MB for the Messages API).", "provider": "ANTHROPIC", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "request_too_large" }, { "checked_on": "2026-09-28", "code": "rate_limit_error", "default_for_status": true, "diagnosis": "RATE_LIMITED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Honour the retry-after header and anthropic-ratelimit-* headers.", "Ramp traffic gradually; a spend-cap 429 needs a limit change, not a retry." ], "http_status": 429, "id": "anthropic.rate_limit_error", "likely_owner": "caller", "meaning": "The organization hit a rate limit (or a usage tier / workspace spend cap).", "provider": "ANTHROPIC", "retry_guidance": "Honour Retry-After when present (give up automatically if it exceeds 300 s); otherwise back off exponentially with jitter from 2 s (cap 60 s), at most 4 attempts. A tier spend-cap 429 has no retry-after header and is not transient.", "retryable": true, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "rate_limit_error" }, { "checked_on": "2026-09-28", "code": "api_error", "default_for_status": true, "diagnosis": "SUPPLIER_SERVER_ERROR", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Retry with exponential backoff.", "Report the request-id if it persists." ], "http_status": 500, "id": "anthropic.api_error", "likely_owner": "supplier", "meaning": "An unexpected error occurred internal to Anthropic's systems.", "provider": "ANTHROPIC", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "api_error" }, { "checked_on": "2026-09-28", "code": "timeout_error", "default_for_status": true, "diagnosis": "GATEWAY_TIMEOUT", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Use streaming for long requests (and avoid large max_tokens without streaming).", "Use the Message Batches API for bulk work." ], "http_status": 504, "id": "anthropic.timeout_error", "likely_owner": "supplier", "meaning": "The request timed out while processing.", "provider": "ANTHROPIC", "retry_guidance": "Retry once; for long generations use streaming or the Message Batches API instead of one blocking call.", "retryable": true, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "timeout_error" }, { "checked_on": "2026-09-28", "code": "overloaded_error", "default_for_status": true, "diagnosis": "PROVIDER_OVERLOADED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Back off with jitter and retry.", "Ramp traffic gradually; sharp increases can also trigger acceleration 429s." ], "http_status": 529, "id": "anthropic.overloaded_error", "likely_owner": "supplier", "meaning": "The API is temporarily overloaded (high traffic across users).", "provider": "ANTHROPIC", "retry_guidance": "Transient capacity problem: honour Retry-After if present, otherwise back off exponentially with jitter from 2 s (cap 60 s), at most 4 attempts; ramp traffic back gradually.", "retryable": true, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "overloaded_error" }, { "checked_on": "2026-09-28", "code": "invalid_request_error: prompt is too long", "diagnosis": "CONTEXT_LENGTH_EXCEEDED", "evidence": "OBSERVED_API_RESPONSE", "family": "LLM_PROVIDER", "fix_steps": [ "Count tokens with the token-counting endpoint before sending.", "Trim or summarise conversation history, or lower max_tokens.", "Use a model with a larger context window." ], "http_status": 400, "id": "anthropic.prompt_too_long", "likely_owner": "caller", "meaning": "The input tokens (plus max_tokens) exceed the model's context window; returned as a 400 invalid_request_error.", "message_patterns": [ "prompt is too long", "input length and `?max_tokens`? exceed context limit", "exceed(s)? (the )?context (limit|window)" ], "note": "The error page lists the invalid_request_error type; the message text is as observed in published API responses.", "provider": "ANTHROPIC", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://platform.claude.com/docs/en/api/errors", "type": "invalid_request_error" }, { "aliases": [ "invalid_request", "parameter_unknown" ], "checked_on": "2026-09-28", "code": "INVALID_ARGUMENT", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check the request against the API reference (field names, model-specific parameters).", "Resend once corrected." ], "grpc_status": "INVALID_ARGUMENT", "http_status": 400, "id": "gemini.invalid_argument", "likely_owner": "caller", "meaning": "The request payload is malformed or contains invalid or unknown parameters.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "INVALID_ARGUMENT" }, { "aliases": [ "failed_precondition" ], "checked_on": "2026-09-28", "code": "FAILED_PRECONDITION", "diagnosis": "FORBIDDEN", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Enable billing / check account prerequisites in Google AI Studio.", "Check regional availability." ], "grpc_status": "FAILED_PRECONDITION", "http_status": 400, "id": "gemini.failed_precondition", "likely_owner": "caller", "meaning": "A prerequisite is not met (for example billing not enabled, or the free tier is unavailable in the caller's region).", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "FAILED_PRECONDITION" }, { "aliases": [ "out_of_range" ], "checked_on": "2026-09-28", "code": "OUT_OF_RANGE", "default_for_status": true, "diagnosis": "BAD_REQUEST", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Validate parameter values and limits." ], "grpc_status": "OUT_OF_RANGE", "http_status": 416, "id": "gemini.out_of_range", "likely_owner": "caller", "meaning": "A request parameter is outside the valid range.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "OUT_OF_RANGE" }, { "aliases": [ "authentication" ], "checked_on": "2026-09-28", "code": "UNAUTHENTICATED", "default_for_status": true, "diagnosis": "AUTH_REQUIRED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check the x-goog-api-key header or key parameter.", "Create a new key and retry once." ], "grpc_status": "UNAUTHENTICATED", "http_status": 401, "id": "gemini.unauthenticated", "likely_owner": "caller", "meaning": "The API key is missing, invalid or expired.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "UNAUTHENTICATED" }, { "aliases": [ "payment_required" ], "checked_on": "2026-09-28", "code": "PAYMENT_REQUIRED", "default_for_status": true, "diagnosis": "BILLING_REQUIRED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Add credits or enable auto-reload." ], "grpc_status": "PAYMENT_REQUIRED", "http_status": 402, "id": "gemini.payment_required", "likely_owner": "caller", "meaning": "The prepaid credit balance is depleted.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "PAYMENT_REQUIRED" }, { "aliases": [ "permission_denied" ], "checked_on": "2026-09-28", "code": "PERMISSION_DENIED", "default_for_status": true, "diagnosis": "FORBIDDEN", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check key restrictions and project access.", "Authenticate correctly for tuned models." ], "grpc_status": "PERMISSION_DENIED", "http_status": 403, "id": "gemini.permission_denied", "likely_owner": "caller", "meaning": "The API key does not have permission for this resource (for example a tuned model it does not own).", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "PERMISSION_DENIED" }, { "aliases": [ "not_found", "model_not_found" ], "checked_on": "2026-09-28", "code": "NOT_FOUND", "default_for_status": true, "diagnosis": "NOT_FOUND", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check the model name and API version (v1 vs v1beta).", "Use an available model and retry once." ], "grpc_status": "NOT_FOUND", "http_status": 404, "id": "gemini.not_found", "likely_owner": "caller", "meaning": "The requested resource (model, file, cached content) was not found.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "NOT_FOUND" }, { "aliases": [ "aborted" ], "checked_on": "2026-09-28", "code": "ABORTED", "default_for_status": true, "diagnosis": null, "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Re-read state and retry." ], "grpc_status": "ABORTED", "http_status": 409, "id": "gemini.aborted", "likely_owner": "caller", "meaning": "The operation was aborted due to a conflict or concurrency check failure.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Retry at the application level with backoff (1 s base, 30 s cap, 3 attempts).", "retryable": true, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "ABORTED" }, { "aliases": [ "already_exists" ], "checked_on": "2026-09-28", "code": "ALREADY_EXISTS", "diagnosis": "CONFLICT", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check whether the resource exists before creating it." ], "grpc_status": "ALREADY_EXISTS", "http_status": 409, "id": "gemini.already_exists", "likely_owner": "caller", "meaning": "The entity to create already exists.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "ALREADY_EXISTS" }, { "aliases": [ "rate_limit_exceeded", "too_many_requests" ], "checked_on": "2026-09-28", "code": "RESOURCE_EXHAUSTED", "default_for_status": true, "diagnosis": "RATE_LIMITED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Back off exponentially with jitter.", "Check the rate limits for the model and tier; request an increase if sustained." ], "grpc_status": "RESOURCE_EXHAUSTED", "http_status": 429, "id": "gemini.resource_exhausted", "likely_owner": "caller", "meaning": "Per-minute/per-second request or token rate limits exceeded.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Honour Retry-After when present (give up automatically if it exceeds 300 s); otherwise back off exponentially with jitter from 2 s (cap 60 s), at most 4 attempts.", "retryable": true, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "RESOURCE_EXHAUSTED" }, { "checked_on": "2026-09-28", "code": "quota_exceeded", "diagnosis": "QUOTA_EXHAUSTED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Wait for the daily reset.", "Request a quota increase or move to a paid tier." ], "http_status": 429, "id": "gemini.quota_exceeded", "likely_owner": "caller", "meaning": "The daily quota is exhausted; retrying before the reset will keep failing.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Not transient within the day: wait for the quota reset or request an increase.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors" }, { "aliases": [ "cancelled" ], "checked_on": "2026-09-28", "code": "CANCELLED", "default_for_status": true, "diagnosis": null, "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check client-side cancellation and deadlines." ], "grpc_status": "CANCELLED", "http_status": 499, "id": "gemini.cancelled", "likely_owner": "caller", "meaning": "The client cancelled the request before completion.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "No action; the client disconnected or its deadline passed.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "CANCELLED" }, { "aliases": [ "api_error", "UNKNOWN" ], "checked_on": "2026-09-28", "code": "INTERNAL", "default_for_status": true, "diagnosis": "SUPPLIER_SERVER_ERROR", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Retry with backoff.", "Reduce input context or switch model temporarily if it persists." ], "grpc_status": "INTERNAL", "http_status": 500, "id": "gemini.internal", "likely_owner": "supplier", "meaning": "An unexpected error occurred on Google's side (sometimes triggered by very long input context).", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Retry with exponential backoff and full jitter (1 s base, 30 s cap, 3 attempts); idempotent calls or calls with an idempotency key only.", "retryable": true, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "INTERNAL" }, { "aliases": [ "unimplemented", "NOT_IMPLEMENTED" ], "checked_on": "2026-09-28", "code": "UNIMPLEMENTED", "default_for_status": true, "diagnosis": "NOT_IMPLEMENTED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Check model capabilities; use a supported alternative." ], "grpc_status": "UNIMPLEMENTED", "http_status": 501, "id": "gemini.unimplemented", "likely_owner": "supplier", "meaning": "The operation or feature is not implemented or supported.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "UNIMPLEMENTED" }, { "aliases": [ "service_unavailable" ], "checked_on": "2026-09-28", "code": "UNAVAILABLE", "default_for_status": true, "diagnosis": "PROVIDER_OVERLOADED", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Back off and retry.", "Switch temporarily to another model if urgent." ], "grpc_status": "UNAVAILABLE", "http_status": 503, "id": "gemini.unavailable", "likely_owner": "supplier", "meaning": "The service is temporarily overloaded or down.", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Transient capacity problem: honour Retry-After if present, otherwise back off exponentially with jitter from 2 s (cap 60 s), at most 4 attempts; ramp traffic back gradually.", "retryable": true, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "UNAVAILABLE" }, { "aliases": [ "deadline_exceeded" ], "checked_on": "2026-09-28", "code": "DEADLINE_EXCEEDED", "default_for_status": true, "diagnosis": "GATEWAY_TIMEOUT", "evidence": "PROVIDER_DOCS", "family": "LLM_PROVIDER", "fix_steps": [ "Increase the client timeout/deadline.", "Reduce prompt or context size." ], "grpc_status": "DEADLINE_EXCEEDED", "http_status": 504, "id": "gemini.deadline_exceeded", "likely_owner": "supplier", "meaning": "The request did not finish within the deadline (prompt or context too large for the deadline).", "note": "google.rpc status names per Google API design guidance; snake_case codes per the Gemini API errors page.", "provider": "GOOGLE_GEMINI", "retry_guidance": "Retry once with a larger client deadline; reduce input size.", "retryable": true, "spec_url": "https://ai.google.dev/gemini-api/docs/api-errors", "type": "DEADLINE_EXCEEDED" }, { "checked_on": "2026-09-28", "code": "API_KEY_INVALID", "diagnosis": "AUTH_REQUIRED", "evidence": "OBSERVED_API_RESPONSE", "family": "LLM_PROVIDER", "fix_steps": [ "Check the key value and that it is for the Generative Language API.", "Create a new key and retry once." ], "http_status": 400, "id": "gemini.api_key_invalid", "likely_owner": "caller", "meaning": "API key not valid: Gemini answers 400 INVALID_ARGUMENT (reason API_KEY_INVALID) for a bad key.", "message_patterns": [ "api key not valid", "API_KEY_INVALID" ], "provider": "GOOGLE_GEMINI", "requires_pattern": true, "retry_guidance": "Retry once only after the listed fix is applied.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/troubleshooting", "type": "INVALID_ARGUMENT" }, { "checked_on": "2026-09-28", "code": "INVALID_ARGUMENT: input token count exceeds maximum", "diagnosis": "CONTEXT_LENGTH_EXCEEDED", "evidence": "OBSERVED_API_RESPONSE", "family": "LLM_PROVIDER", "fix_steps": [ "Count tokens (models.countTokens) before sending.", "Trim input or use context caching / a larger-context model." ], "http_status": 400, "id": "gemini.input_token_limit", "likely_owner": "caller", "meaning": "The input token count exceeds the model's maximum input tokens.", "message_patterns": [ "input token count.{0,40}exceeds the maximum", "exceeds the maximum number of tokens allowed" ], "provider": "GOOGLE_GEMINI", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/troubleshooting", "type": "INVALID_ARGUMENT" }, { "checked_on": "2026-09-28", "code": "FAILED_PRECONDITION: user location not supported", "diagnosis": "FORBIDDEN", "evidence": "OBSERVED_API_RESPONSE", "family": "LLM_PROVIDER", "fix_steps": [ "Check the available regions list; do not route around the restriction." ], "http_status": 400, "id": "gemini.user_location", "likely_owner": "caller", "meaning": "The API is not available in the caller's location (or the free tier is not available there).", "message_patterns": [ "user location is not supported" ], "provider": "GOOGLE_GEMINI", "requires_pattern": true, "retry_guidance": "Do not resend the same request; fix the cause first, then send once.", "retryable": false, "spec_url": "https://ai.google.dev/gemini-api/docs/troubleshooting", "type": "FAILED_PRECONDITION" } ], "entry_count": 111, "fields": { "code": "Error code or type as the source publishes it.", "default_for_status": "Entry may match on HTTP status alone once the provider is known.", "diagnosis": "GAIP Integration Repair diagnosis this entry maps to (null keeps the status-based diagnosis).", "evidence": "SPEC | PROVIDER_DOCS | SDK_SOURCE | OBSERVED_API_RESPONSE (message text seen in published API responses).", "fix_steps": "Ordered steps to fix.", "likely_owner": "caller | supplier | network: who most likely has to act.", "meaning": "What the error means.", "message_patterns": "Case-insensitive regular expressions matched against the error text.", "requires_pattern": "Entry only matches when a message pattern matches.", "retry_guidance": "How to retry (or why not).", "retryable": "Whether an automatic retry can succeed without a change." }, "governance": { "note": "Diagnoses are guidance from public specifications and provider documentation, not a finding of fault.", "personal_data": false, "public_knowledge_only": true, "read_only": true, "verdict_for_money": false }, "kb_version": "1.0.0", "provider_detection": { "A2A / MCP / JSON_RPC": "JSON-RPC error object; A2A vs MCP from the declared protocol.", "ANTHROPIC": "Body {type: 'error', error: {type, message}} with an Anthropic error type, HTTP 529, or 'anthropic'/'claude' markers.", "GOOGLE_GEMINI": "Body {error: {code: , message, status: }}, generativelanguage.googleapis.com/gemini markers.", "HTTP": "HTTP status only.", "OPENAI": "Body {error: {message, type, param, code}} (the 'param' member), OpenAI error codes, or 'openai' markers." }, "providers": [ "A2A", "ANTHROPIC", "GOOGLE_GEMINI", "HTTP", "JSON_RPC", "MCP", "OPENAI" ], "schema_version": "gaip.error-kb.v1", "sources": [ { "title": "RFC 9110 HTTP Semantics", "url": "https://www.rfc-editor.org/rfc/rfc9110.html" }, { "title": "RFC 6585 Additional HTTP Status Codes", "url": "https://www.rfc-editor.org/rfc/rfc6585.html" }, { "title": "RFC 9457 Problem Details for HTTP APIs", "url": "https://www.rfc-editor.org/rfc/rfc9457.html" }, { "title": "RFC 8470 Using Early Data in HTTP", "url": "https://www.rfc-editor.org/rfc/rfc8470.html" }, { "title": "RFC 7725 HTTP 451", "url": "https://www.rfc-editor.org/rfc/rfc7725.html" }, { "title": "RFC 4918 WebDAV (507)", "url": "https://www.rfc-editor.org/rfc/rfc4918.html" }, { "title": "JSON-RPC 2.0 Specification", "url": "https://www.jsonrpc.org/specification" }, { "title": "A2A Protocol Specification 1.0.0", "url": "https://a2a-protocol.org/latest/specification/" }, { "title": "MCP Specification 2025-11-25", "url": "https://modelcontextprotocol.io/specification/2025-11-25" }, { "title": "MCP TypeScript SDK ErrorCode", "url": "https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/types.ts" }, { "title": "OpenAI API error codes", "url": "https://developers.openai.com/api/docs/guides/error-codes" }, { "title": "Claude API errors", "url": "https://platform.claude.com/docs/en/api/errors" }, { "title": "Gemini API errors", "url": "https://ai.google.dev/gemini-api/docs/api-errors" }, { "title": "Gemini API troubleshooting", "url": "https://ai.google.dev/gemini-api/docs/troubleshooting" }, { "title": "Google AIP-193 Errors", "url": "https://google.aip.dev/193" }, { "title": "google.rpc.Code definitions", "url": "https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto" } ] }