# HTTP Error Codes Reference This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the \`python/\` or \`typescript/\` folders. ## Error Code Summary | Code | Name | Retryable | Common Cause | | ---- | --------------------- | --------- | ------------------------------------ | | 400 | Bad Request | No | Invalid request format or parameters | | 401 | Unauthorized | No | Invalid or missing API key | | 403 | Forbidden | No | API key lacks permission | | 404 | Not Found | No | Invalid endpoint or model ID | | 413 | Request Too Large | No | Request exceeds size limits | | 422 | Unprocessable Entity | No | Semantic validation error | | 429 | Rate Limited | Yes | Too many requests | | 500 | Internal Server Error | Yes | Anthropic service issue | | 529 | Overloaded | Yes | API is temporarily overloaded | ## Detailed Error Information ### 400 Bad Request **Causes:** - Malformed JSON in request body - Missing required parameters (\`model\`, \`max_tokens\`, \`messages\`) - Invalid parameter types (e.g., string where integer expected) - Empty messages array - Messages not alternating user/assistant **Example error:** \`\`\`json { "type": "error", "error": { "type": "invalid_request_error", "message": "messages: roles must alternate between \\"user\\" and \\"assistant\\"" } } \`\`\` **Fix:** Validate request structure before sending. Check that: - \`model\` is a valid model ID - \`max_tokens\` is a positive integer - \`messages\` array is non-empty and alternates correctly --- ### 401 Unauthorized **Causes:** - Missing \`x-api-key\` header or \`Authorization\` header - Invalid API key format - Revoked or deleted API key **Fix:** Ensure \`ANTHROPIC_API_KEY\` environment variable is set correctly. --- ### 403 Forbidden **Causes:** - API key doesn't have access to the requested model - Organization-level restrictions - Attempting to access beta features without beta access **Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features. --- ### 404 Not Found **Causes:** - Typo in model ID (e.g., \`claude-sonnet-4.6\` instead of \`claude-sonnet-4-6\`) - Using deprecated model ID - Invalid API endpoint **Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., \`claude-opus-4-6\`). --- ### 413 Request Too Large **Causes:** - Request body exceeds maximum size - Too many tokens in input - Image data too large **Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks. --- ### 422 Unprocessable Entity **Causes:** - \`max_tokens\` exceeds model's limit - Invalid \`temperature\` value (must be 0.0-1.0) - \`budget_tokens\` >= \`max_tokens\` in extended thinking - Invalid tool definition schema **Common mistake with extended thinking:** \`\`\` # Wrong: budget_tokens must be < max_tokens thinking: budget_tokens=10000, max_tokens=1000 → Error! # Correct thinking: budget_tokens=10000, max_tokens=16000 \`\`\` --- ### 429 Rate Limited **Causes:** - Exceeded requests per minute (RPM) - Exceeded tokens per minute (TPM) - Exceeded tokens per day (TPD) **Headers to check:** - \`retry-after\`: Seconds to wait before retrying - \`x-ratelimit-limit-*\`: Your limits - \`x-ratelimit-remaining-*\`: Remaining quota **Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: \`max_retries=2\`). For custom retry behavior, see the language-specific error handling examples. --- ### 500 Internal Server Error **Causes:** - Temporary Anthropic service issue - Bug in API processing **Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com). --- ### 529 Overloaded **Causes:** - High API demand - Service capacity reached **Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing. --- ## Common Mistakes and Fixes | Mistake | Error | Fix | | ------------------------------- | ---------------- | ------------------------------------------------------- | | \`budget_tokens\` >= \`max_tokens\` | 422 | Ensure \`budget_tokens\` < \`max_tokens\` | | Typo in model ID | 404 | Use valid model ID like \`claude-opus-4-6\` | | First message is \`assistant\` | 400 | First message must be \`user\` | | Consecutive same-role messages | 400 | Alternate \`user\` and \`assistant\` | | API key in code | 401 (leaked key) | Use environment variable | | Custom retry needs | 429/5xx | SDK retries automatically; customize with \`max_retries\` |