CCA-F › Domain 5 › Error Handling — Who Catches What

🧯 Who Catches What — 400 vs refusal vs is_error

Server-side validation vs a model decision vs your app · and every reason a request 400s

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.

So your example — a 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.

flowchart TD R["Your request"] --> A{"Auth?"} A -->|"bad/missing key"| E401["401 / 403"]:::err A -->|ok| RL{"Under rate limit?"} RL -->|"no"| E429["429"]:::err RL -->|ok| SZ{"Within size?"} SZ -->|"too big"| E413["413"]:::err SZ -->|ok| V{"VALIDATION
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.

SignalCaught byHTTPBilled?Example
Invalid request (400)Server — before the model400 errorNomalformed messages, bad params, broken tool pairing
Refusal (stop_reason:"refusal")The model / safety classifier200 OKYes (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 model200Yesa tool you ran failed → the model self-corrects
Truncation (stop_reason:"max_tokens")The model hit the output cap200Yesoutput cut off mid-answer
A refusal is NOT a 400. It's a successful HTTP 200 the model chose to decline — always check 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

B · Malformed / missing basics

C · Parameter constraint violations

D · Model-specific 400s (current models — Opus 4.8/4.7, Sonnet 5, Fable 5)

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.

This is exactly why a correct agent loop appends the whole assistant turn and returns all tool_results in one user message — it satisfies the tool contract and avoids these 400s. See D2 · Tool-Result Contract Failures.

EXAM ONE-LINERS

• 400 = server-side validation, before the model, unbilled, deterministic — the LLM never sees an invalid request.
• 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.
These are all the loud failures — a signal fires. The far more dangerous class is the silent one: a valid request that returns 200 + end_turn with no flag, and a wrong answer. → Silent failures — passes but wrong.