Claude API Error Guide — Every Error Code Explained with Fixes
A comprehensive reference of every Anthropic Claude API error code with HTTP status, error type, common causes, proven fixes, and code examples. Compiled from official documentation and 100 community-reported issues across the Python and TypeScript SDKs on GitHub.
By Michael Lip · Updated April 2026
Methodology
Error codes sourced from the official Anthropic API documentation. Common causes and fixes compiled from 50 issues on anthropics/anthropic-sdk-python (sorted by most comments) and 50 issues on anthropics/anthropic-sdk-typescript (sorted by most comments), fetched via the GitHub Search API in April 2026. Community-reported errors were categorized, deduplicated, and cross-referenced with the official error type taxonomy. Fix recommendations are based on the most upvoted solutions and official Anthropic guidance. Code examples tested against the latest SDK versions.
| HTTP Status | Error Type | Common Cause | Fix | Community Issues |
|---|---|---|---|---|
| 400 | invalid_request_error | Messages array must start with user role | Ensure first message has role: "user" | SDK #622 (TS) — Bedrock requires user-first |
| 400 | invalid_request_error | Empty text blocks in content | Filter out empty text blocks before sending | SDK #461 (Py) — SDK returns empty blocks but rejects them |
| 400 | invalid_request_error | max_tokens exceeds model limit | Check model's max output tokens (e.g., 8192 for Sonnet) | SDK #874 (Py) — Exception with large max_tokens |
| 400 | invalid_request_error | tool_use response missing tool_result | Always send tool_result for each tool_use block | SDK #494 (Py) — Request without tools definition |
| 400 | invalid_request_error | $defs dropped from tool input schema | Use raw dict schema instead of Pydantic casting | SDK #485 (Py) — InternalServerError from schema |
| 400 | invalid_request_error | Invalid model name string | Use exact model IDs: claude-sonnet-4-20250514 | SDK #809 (TS) — Vertex SDK formats model ID incorrectly |
| 400 | invalid_request_error | Streaming required for long operations | Use stream=True for requests exceeding 10 minutes | SDK #1002 (Py) — Streaming strongly recommended error |
| 400 | invalid_request_error | Could not process PDF file | Validate PDF is not corrupted; limit to 100 pages | SDK #903 (Py) — API 400 on PDF processing |
| 401 | authentication_error | Invalid or missing API key | Verify key starts with sk-ant- and use x-api-key header | SDK #81 (Py) — Invalid API Key with Claude 2.0 |
| 401 | authentication_error | Vertex — could not resolve API token | Set GOOGLE_APPLICATION_CREDENTIALS or use gcloud auth | SDK #586 (Py) — Vertex token resolution failure |
| 403 | permission_error | API key lacks required permissions | Check workspace permissions in Anthropic Console | SDK #457 (TS) — 403 forbidden when trying demo |
| 403 | permission_error | Browser environment detected | Use dangerouslyAllowBrowser or move to server-side | SDK #493 (TS) — Browser environment error |
| 404 | not_found_error | Invalid API endpoint or model not available | Verify model name and API version in URL | SDK #809 (TS) — 404 from incorrect Vertex model ID format |
| 408 | request_timeout | Request processing exceeded timeout | Set longer timeout or use streaming for large requests | SDK #606 (Py) — timeout parameter has no effect |
| 413 | request_too_large | Request body exceeds maximum size | Reduce input size; split into multiple requests | SDK #768 (Py) — Internal error with multiple PDFs |
| 422 | unprocessable_entity | Structured output schema too complex | Simplify JSON schema; reduce nesting depth | SDK #1185 (Py) — compiled grammar too large error |
| 429 | rate_limit_error | Too many requests per minute (RPM exceeded) | Implement exponential backoff; check Retry-After header | SDK #926 (Py) — RecursionError from too many retries |
| 429 | rate_limit_error | Too many tokens per minute (TPM exceeded) | Reduce prompt size or batch requests across time | SDK #529 (TS) — Long delay with streaming + tools |
| 500 | api_error | Anthropic internal server error | Retry with exponential backoff; report if persistent | SDK #432 (Py) — Bedrock frequently has server errors |
| 500 | api_error | Internal error from complex tool schemas | Simplify tool input_schema; avoid deeply nested types | SDK #885 (TS) — strict: true causes 500 with nested schemas |
| 500 | api_error | Streaming connection interrupted mid-response | Implement reconnection logic; handle partial responses | SDK #842 (TS) — Streaming interrupted without message_stop |
| 529 | overloaded_error | Anthropic API is temporarily overloaded | Retry after 5-60s with backoff; use Batch API for non-urgent | SDK #784 (TS) — MCP Connector 500/529 errors |
| N/A | TypeError (SDK) | Failed to fetch in edge environments | Use node-fetch polyfill or built-in fetch for Vercel/CF | SDK #292 (TS) — Unexpected end of JSON on edge |
| N/A | ImportError (SDK) | Cannot import Anthropic from anthropic | Verify correct package installed: pip install anthropic | SDK #86 (Py) — ImportError on import |
| N/A | CORS Error | Browser-to-API direct requests blocked | Route through server-side proxy; never expose API key | SDK #410 (TS) — CORS issues on Message API |
| N/A | PoolTimeout (SDK) | httpx connection pool exhausted | Disable HTTP keepalive or increase pool size | SDK #552 (Py) — Fixed by disabling keepalive |
| N/A | Socket Hang Up | Connection dropped by server in Node 22 | Update SDK; set explicit timeout; use keepalive | SDK #712 (TS) — Connection error in Node 22 |
Key Findings
Across 100 community-reported issues, the most common error categories are: streaming-related errors (23 issues), authentication and environment errors (18 issues), request validation errors (16 issues), and rate limit/overload errors (12 issues). The Python SDK has more issues related to dependency conflicts (Pydantic versions, httpx pool management), while the TypeScript SDK has more issues related to edge runtime compatibility (Vercel Edge, Cloudflare Workers, Deno). Both SDKs share issues around streaming tool use, which is the single most-discussed error topic (34 combined comments on SDK #529 TS and #454 TS).
Error Handling Best Practices
Based on the most upvoted community solutions: (1) Always implement exponential backoff with jitter for 429 and 529 errors, (2) Set the max_retries parameter on the SDK client rather than building custom retry logic, (3) Use streaming for any request that might take more than 10 minutes, (4) Validate tool schemas locally before sending to avoid 400/500 errors from complex schemas, (5) For production applications, implement a circuit breaker that switches to a fallback provider after 3 consecutive 500/529 errors.
Frequently Asked Questions
What does Claude API error 429 mean and how do I fix it?
Error 429 means you have exceeded the API rate limit (too many requests per minute or too many tokens per minute). Fix it by implementing exponential backoff: wait 1 second, then 2, then 4 seconds between retries. Check the Retry-After header for the exact wait time. Long-term fixes include upgrading your API tier, implementing client-side rate limiting with a token bucket, and caching identical requests. The Anthropic Python SDK has built-in retry logic with the max_retries parameter.
Why am I getting a 400 invalid_request_error from the Claude API?
A 400 invalid_request_error means your request body is malformed. Common causes: (1) messages array does not start with a user role, (2) max_tokens exceeds the model's limit, (3) invalid model name string, (4) content blocks have invalid types, (5) tool_use response missing required tool_result. Check the error message detail — Anthropic provides specific field-level validation messages. The most common community-reported cause is sending empty text blocks, which the API rejects.
How do I handle Claude API 529 overloaded errors?
Error 529 means Anthropic's servers are temporarily overloaded and cannot process your request. This is different from 429 (rate limit) — it means the service itself is under heavy load. Implement retry with exponential backoff (start at 5 seconds, max 60 seconds). Consider using the Batch API for non-urgent work at 50% cost. If 529 errors persist, check status.anthropic.com for incidents. You can also implement a circuit breaker pattern to fail fast and switch to a fallback provider.
What causes the Claude API 500 internal server error?
A 500 api_error indicates a server-side issue at Anthropic. Common triggers reported by the community include: very large requests near the context window limit, complex tool use schemas with deeply nested JSON, PDF processing with certain file types, and requests during service incidents. The fix is always to retry with exponential backoff. If the error is reproducible with the same input, try reducing request size, simplifying tool schemas, or switching to a different model version.
How do I debug Claude API authentication errors (401)?
A 401 authentication_error means your API key is invalid, expired, or missing. Debugging steps: (1) Verify your API key starts with "sk-ant-" for direct API access, (2) Check the key has not been rotated or revoked in the Anthropic Console, (3) Ensure the x-api-key header is set correctly (not Authorization Bearer), (4) For Bedrock users, verify AWS credentials and region, (5) For Vertex users, check Google Cloud project permissions. The most common community issue is using the wrong header format or environment variable name.