1# HTTP Error Codes Reference
2 
3This 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.
4 
5## Error Code Summary
6 
7| Code | Error Type              | Retryable | Common Cause                         |
8| ---- | ----------------------- | --------- | ------------------------------------ |
9| 400  | `invalid_request_error` | No        | Invalid request format or parameters |
10| 401  | `authentication_error`  | No        | Invalid or missing API key           |
11| 403  | `permission_error`      | No        | API key lacks permission             |
12| 404  | `not_found_error`       | No        | Invalid endpoint or model ID         |
13| 413  | `request_too_large`     | No        | Request exceeds size limits          |
14| 429  | `rate_limit_error`      | Yes       | Too many requests                    |
15| 500  | `api_error`             | Yes       | Anthropic service issue              |
16| 529  | `overloaded_error`      | Yes       | API is temporarily overloaded        |
17 
18## Detailed Error Information
19 
20### 400 Bad Request
21 
22**Causes:**
23 
24- Malformed JSON in request body
25- Missing required parameters (`model`, `max_tokens`, `messages`)
26- Invalid parameter types (e.g., string where integer expected)
27- Empty messages array
28- Messages not alternating user/assistant
29 
30**Example error:**
31 
32```json
33{
34  "type": "error",
35  "error": {
36    "type": "invalid_request_error",
37    "message": "messages: roles must alternate between \"user\" and \"assistant\""
38  },
39  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
40}
41```
42 
43**Fix:** Validate request structure before sending. Check that:
44 
45- `model` is a valid model ID
46- `max_tokens` is a positive integer
47- `messages` array is non-empty and alternates correctly
48 
49---
50 
51### 401 Unauthorized
52 
53**Causes:**
54 
55- Missing `x-api-key` header or `Authorization` header
56- Invalid API key format
57- Revoked or deleted API key
58- OAuth bearer token sent via `x-api-key` instead of `Authorization: Bearer`
59- Both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` set — the SDK sends both headers and the API rejects the request
60 
61**Fix:** Set `ANTHROPIC_API_KEY`, or run `ant auth login` and leave the client constructor empty. For raw HTTP with an OAuth token, use `Authorization: Bearer <token>` (not `x-api-key:`).
62 
63---
64 
65### 403 Forbidden
66 
67**Causes:**
68 
69- API key doesn't have access to the requested model
70- Organization-level restrictions
71- Attempting to access beta features without beta access
72 
73**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
74 
75---
76 
77### 404 Not Found
78 
79**Causes:**
80 
81- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`)
82- Using deprecated model ID
83- Invalid API endpoint
84 
85**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-8`).
86 
87---
88 
89### 413 Request Too Large
90 
91**Causes:**
92 
93- Request body exceeds maximum size
94- Too many tokens in input
95- Image data too large
96 
97**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
98 
99---
100 
101### 400 Validation Errors
102 
103Some 400 errors are specifically related to parameter validation:
104 
105- `max_tokens` exceeds model's limit
106- Invalid `temperature` value (must be 0.0-1.0)
107- `budget_tokens` >= `max_tokens` in extended thinking
108- Invalid tool definition schema
109 
110**Model-specific 400s on Fable 5 / Opus 4.8 / 4.7:**
111 
112- `temperature`, `top_p`, `top_k` are removed — sending any of them returns 400. Delete the parameter; see `shared/model-migration.md` → Per-SDK Syntax Reference.
113- `thinking: {type: "enabled", budget_tokens: N}` is removed — sending it returns 400. Use `thinking: {type: "adaptive"}` instead.
114- **Fable 5 only:** an explicit `thinking: {type: "disabled"}` returns 400 (it is accepted on Opus 4.8/4.7). Omit the `thinking` param entirely instead.
115- **Fable 5 only:** if the organization is set to zero data retention (ZDR) — or any retention below the required 30 days — then **all** Fable 5 requests return `400 invalid_request_error`, even with a perfectly valid payload. Check the org's retention configuration before debugging the request body.
116 
117**Common mistake with extended thinking on older models (Opus 4.6 and earlier):**
118 
119```
120# Wrong: budget_tokens must be < max_tokens
121thinking: budget_tokens=10000, max_tokens=1000  → Error!
122 
123# Correct
124thinking: budget_tokens=10000, max_tokens=16000
125```
126 
127---
128 
129### 429 Rate Limited
130 
131**Causes:**
132 
133- Exceeded requests per minute (RPM)
134- Exceeded tokens per minute (TPM)
135- Exceeded tokens per day (TPD)
136 
137**Headers to check:**
138 
139- `retry-after`: Seconds to wait before retrying
140- `x-ratelimit-limit-*`: Your limits
141- `x-ratelimit-remaining-*`: Remaining quota
142 
143**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.
144 
145---
146 
147### 500 Internal Server Error
148 
149**Causes:**
150 
151- Temporary Anthropic service issue
152- Bug in API processing
153 
154**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com).
155 
156---
157 
158### 529 Overloaded
159 
160**Causes:**
161 
162- High API demand
163- Service capacity reached
164 
165**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
166 
167---
168 
169## Common Mistakes and Fixes
170 
171| Mistake                         | Error            | Fix                                                     |
172| ------------------------------- | ---------------- | ------------------------------------------------------- |
173| `temperature`/`top_p`/`top_k` on Fable 5 / Opus 4.8 / 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`)  |
174| `budget_tokens` on Fable 5 / Opus 4.8 / 4.7 | 400  | Use `thinking: {type: "adaptive"}`                      |
175| `thinking: {type: "disabled"}` on Fable 5 | 400    | Omit the `thinking` param entirely (accepted on Opus 4.8/4.7) |
176| Org set to ZDR / retention below 30 days (Fable 5) | 400 on every request | Fix the org's data-retention configuration — the payload isn't the problem |
177| `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens`                  |
178| Typo in model ID                | 404              | Use valid model ID like `claude-opus-4-8`               |
179| First message is `assistant`    | 400              | First message must be `user`                            |
180| Consecutive same-role messages  | 400              | Alternate `user` and `assistant`                        |
181| API key in code                 | 401 (leaked key) | Use environment variable                                |
182| Custom retry needs              | 429/5xx          | SDK retries automatically; customize with `max_retries` |
183 
184## Typed Exceptions in SDKs
185 
186**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:
187 
188| HTTP Code | TypeScript Class                  | Python Class                      |
189| --------- | --------------------------------- | --------------------------------- |
190| 400       | `Anthropic.BadRequestError`       | `anthropic.BadRequestError`       |
191| 401       | `Anthropic.AuthenticationError`   | `anthropic.AuthenticationError`   |
192| 403       | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` |
193| 404       | `Anthropic.NotFoundError`         | `anthropic.NotFoundError`         |
194| 413       | `Anthropic.RequestTooLargeError`  | `anthropic.RequestTooLargeError`  |
195| 429       | `Anthropic.RateLimitError`        | `anthropic.RateLimitError`        |
196| 500+      | `Anthropic.InternalServerError`   | `anthropic.InternalServerError`   |
197| 529       | `Anthropic.OverloadedError`       | `anthropic.OverloadedError`       |
198| Any       | `Anthropic.APIError`              | `anthropic.APIError`              |
199 
200```typescript
201// ✅ Correct: use typed exceptions
202try {
203  const response = await client.messages.create({...});
204} catch (error) {
205  if (error instanceof Anthropic.RateLimitError) {
206    // Handle rate limiting
207  } else if (error instanceof Anthropic.APIError) {
208    console.error(`API error ${error.status}:`, error.message);
209  }
210}
211 
212// ❌ Wrong: don't check error messages with string matching
213try {
214  const response = await client.messages.create({...});
215} catch (error) {
216  const msg = error instanceof Error ? error.message : String(error);
217  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
218}
219```
220 
221All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`).
222 
223### Error `.type` Field
224 
225All `APIStatusError` subclasses now expose a `.type` property (Python: `.type`, TypeScript: `.type`, Java: `.errorType()`, Go: `.Type()`, Ruby: `.type`, PHP: `.type`) that returns the API error type string (e.g., `"invalid_request_error"`, `"authentication_error"`, `"rate_limit_error"`, `"overloaded_error"`). Use this for programmatic error classification when you need finer granularity than the HTTP status code — for example, distinguishing `"billing_error"` from `"permission_error"` (both map to 403).
226 
227```python
228except anthropic.APIStatusError as e:
229    if e.type == "rate_limit_error":
230        # handle rate limiting
231    elif e.type == "overloaded_error":
232        # handle overload
233```
234