The max_tokens parameter is a hard ceiling on how much a Claude model may generate in one response. The detail teams miss when they enable thinking: that ceiling covers everything the model generates — reasoning and answer together. Anthropic's adaptive-thinking documentation states it directly: thinking tokens count toward max_tokens, which is a hard limit on thinking plus response text. A model given room for a short answer but a hard problem will burn the allowance deliberating, and the response ends with stop_reason: "max_tokens" — often with a truncated or even empty visible answer.
Recognizing the failure signature
The response arrives with HTTP 200 (this is a body-level condition, like the refusal stop reason — no exception fires). Three fields tell the story together:
| Field | What to look for |
|---|---|
stop_reason | "max_tokens" — generation hit the ceiling rather than finishing |
usage.output_tokens | At or near your max_tokens value (this is the authoritative billed total) |
usage.output_tokens_details.thinking_tokens | How much of that total was reasoning — the smoking gun when it dwarfs the visible text |
If thinking_tokens is a large share of output_tokens, the model didn't write a bad answer — it never got to finish writing one. Note that with summarized or omitted thinking display, the tokens you can see understate what was generated and billed, so always diagnose from the usage fields, not from eyeballing the response. Truncation also has knock-on effects: structured outputs cut off at max_tokens may be incomplete or invalid JSON, so schema validation failures and this stop reason frequently arrive together.
The two real fixes
Anthropic's guidance for this condition is specific: raise max_tokens, or lower the effort level. Rewriting the prompt to "be concise" is treating a budget problem as a style problem.
Raise the ceiling. Give thinking and answer room to coexist. Current models have generous headroom — 128k output tokens on Opus 4.8/4.7, Sonnet 5, Opus 4.6, and Sonnet 4.6 (64k on Haiku 4.5) — and on the Claude API a high max_tokens has no rate-limit downside, because the output-tokens-per-minute limit counts only tokens actually generated, not the ceiling you set. Anthropic's effort guidance even recommends starting around 64k max_tokens when running Opus 4.7/4.8 at xhigh or max effort. The main cost of a big ceiling is the worst-case bill and latency you're willing to tolerate — and note the 10-minute non-streaming validation means very large ceilings effectively require streaming.
Or ask for less deliberation. The output_config: {"effort": ...} parameter (levels max, xhigh, high — the default — medium, low) shapes how many tokens the model spends across thinking, tool calls, and text. Lower effort means less reasoning inside the same ceiling. Effort is a behavioral signal rather than a strict budget — at low effort the model still thinks on genuinely hard problems, just less — which is usually what you want: spend when it matters, save when it doesn't.
max_tokens as expected thinking + longest acceptable answer, not as "the answer length I asked for." Then monitor the ratio of thinking_tokens to output_tokens per task type and tune effort where the ratio runs hot.A note on manual thinking budgets
On older models still using manual extended thinking (thinking: {"type": "enabled", "budget_tokens": N} — e.g. Opus 4.5 and Haiku 4.5; the newest models reject this form), the same ceiling logic applies with one extra constraint: budget_tokens must be less than max_tokens, except when interleaved thinking with tools is active, where the budget is a total across all thinking blocks and can exceed max_tokens. The model may also use far less than its budget, especially above 32k. If you're migrating from budget-based code to adaptive thinking plus effort, the thinking upgrade path covers the mapping.
Where to go next
Effort-versus-cost trade-offs are covered in budgeting extended thinking; how thinking blocks arrive on the wire is in streaming adaptive thinking; the older budget parameter in thinking budgets.