5.4 KiB
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.
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` |