THE ANSWER A 400 is caught before the model runs
An invalid request (HTTP 400, invalid_request_error) is caught by Anthropic's API server at the
validation layer — before any model inference. The LLM never sees a malformed request, and you're
not billed any tokens for a 400. It's deterministic schema/structure/parameter checking, not the model "noticing"
a problem.
tool_result in a user turn with no preceding assistant
tool_use, or an assistant tool_use not followed by its tool_result — is a
structural contract violation caught server-side as 400, never handled by the LLM.PIPELINE Where each error lives
A request passes through stages; a failure at each returns a different code. The model only runs if validation passes.
schema · structure · params"} V -->|"invalid"| E400["400 invalid_request_error
(pre-model · unbilled · deterministic)"]:::stop V -->|"valid"| M["MODEL INFERENCE"]:::ok M --> R200["200 OK + stop_reason:
end_turn · tool_use · max_tokens ·
pause_turn · refusal · stop_sequence"]:::ok M -.->|"outage"| E5xx["500 / 529"]:::err classDef err fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d; classDef stop fill:#fef3c7,stroke:#b45309,color:#7c2d12; classDef ok fill:#dcfce7,stroke:#15803d,color:#14532d;
400 is the validation gate — the model is the next stage and only runs on a valid request.
WHO DECIDES 400 vs refusal vs is_error vs max_tokens
The distinction people get wrong: a structure/parameter problem is a 400 (server); a behavioural outcome
is a successful call (HTTP 200) with a stop_reason the model chose.
| Signal | Caught by | HTTP | Billed? | Example |
|---|---|---|---|---|
Invalid request (400) | Server — before the model | 400 error | No | malformed messages, bad params, broken tool pairing |
Refusal (stop_reason:"refusal") | The model / safety classifier | 200 OK | Yes (or unbilled if declined before any output) | the model declines a request for safety |
Tool failure (tool_result + is_error:true) | Your app telling the model | 200 | Yes | a tool you ran failed → the model self-corrects |
Truncation (stop_reason:"max_tokens") | The model hit the output cap | 200 | Yes | output cut off mid-answer |
stop_reason before reading content. And is_error:true is you
reporting a tool failure into the conversation, not an API error at all.400 CAUSES Every reason a request raises 400
A · Message structure & the tool contract
messagesroles don't alternate user/assistant- first message is
assistant(must beuser) - empty
messagesarray - a
tool_resultwith no matchingtool_usein the preceding assistant turn - an assistant
tool_usenot immediately followed by itstool_result(literal error: "tool_use ids were found without tool_result blocks immediately after") - text/blocks interleaved incorrectly around tool blocks
B · Malformed / missing basics
- malformed JSON body
- missing required params (
model,max_tokens,messages) - wrong parameter types (string where an int is expected)
- invalid tool-definition schema
C · Parameter constraint violations
max_tokensexceeds the model's output limitbudget_tokens >= max_tokens(on models that still use extended thinking)- out-of-range values (e.g. invalid
temperature)
D · Model-specific 400s (current models — Opus 4.8/4.7, Sonnet 5, Fable 5)
- sending
temperature/top_p/top_kat all — removed → 400 thinking:{type:"enabled", budget_tokens:N}— removed → 400 (use{type:"adaptive"})- assistant-turn prefill (last message is
assistant) → 400 on the 4.6/4.7/4.8/Fable-5 family - Fable 5 only: explicit
thinking:{type:"disabled"}→ 400 (omit the param instead) citationscombined withoutput_config.format(structured outputs) → 400- Fable 5 under zero-data-retention / retention below 30 days → every request 400s (org config, not the payload)
413 request_too_large and 429 rate_limit_error are their own codes,
not 400. 401/403 are auth/permission; 500/529 are server-side (retryable).CONSEQUENCE Why SDKs don't retry a 400
Because a 400 is deterministic server-side validation, it never fixes itself. That's why the Anthropic SDKs auto-retry 429 and 5xx (transient) with backoff, but never retry 400 — resending the identical malformed request just 400s again. The fix is always in your request construction.
tool_results in one user message — it satisfies the tool contract and avoids these 400s. See
D2 · Tool-Result Contract Failures.EXAM ONE-LINERS
• refusal is a model decision returned as HTTP 200 with
stop_reason:"refusal" — check
stop_reason before reading content.•
is_error:true on a tool_result is your app reporting a tool failure to the model — not an API error.• SDKs retry 429/5xx, never 400.
end_turn with no flag, and a wrong answer.
→ Silent failures — passes but wrong.