Errors
| Status | Type | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_request_error |
The request is wrong for this model | No — fix it (lint) |
| 401 | authentication_error |
Key missing, wrong or revoked | No |
| 403 | permission_error |
Key lacks access to the model or resource | No |
| 404 | not_found_error |
Unknown model id or resource | No |
| 413 | request_too_large |
Body too large | No |
| 429 | rate_limit_error |
Rate or quota limit | Yes, after retry-after |
| 500 | api_error |
Server error | Yes, with backoff |
| 529 | overloaded_error |
API overloaded | Yes, with backoff |
The SDKs already retry 408, 409, 429 and 5xx twice. Catch typed errors from most to least specific (not-found → rate-limit → API status → connection) instead of one broad handler, and log the request id.
A refusal is not an error: HTTP 200 with stop_reason: "refusal" and a stop_details object.
Check for it before reading content.
400s seen from the live API, and the fix
| The API says | Fix |
|---|---|
"thinking.type.enabled" is not supported for this model… |
thinking: {"type": "adaptive"} + output_config.effort |
"thinking.type.disabled" is not supported for this model… |
Omit thinking, lower effort |
To turn thinking off on this model, send "thinking": {"type": "between_tools"}… |
Sonnet 5.5: do that |
adaptive thinking is not supported on this model |
4.5 models: {"type": "enabled", "budget_tokens": N} |
temperature: Extra inputs are not permitted / `temperature` is deprecated for this model. |
Remove sampling parameters |
tool_choice: type "tool" and "any" are not supported for this model. |
tool_choice: {"type": "auto"} + instruction |
This model does not support assistant message prefill… |
Remove the trailing assistant turn |
role 'system' is not supported on this model |
Use the top-level system field |
max_tokens: N > 128000, which is the maximum allowed… |
Lower max_tokens |
This model does not support the effort parameter. |
Remove output_config.effort |
This model does not support effort level 'xhigh'. Supported levels: … |
Use a listed level |
output_config.effort 'xhigh' is not supported when thinking is disabled… |
Effort high or lower, or enable thinking |
…does not support the \speed` parameter…` |
Remove speed, or use a model with fast mode |
To use the \speed` parameter with '…', send the `anthropic-beta: fast-mode-2026-02-01` header.` |
Add the beta flag |
This model does not support user-configurable task budgets. |
Remove task_budget |
The full list with the model each text came from: references/request-rules.md.