Every Messages API request carries a max_tokens value: the maximum number of tokens the model is allowed to generate for that response. It is a cap, not a target — the model stops naturally whenever it finishes, and you pay only for tokens actually generated. The failure mode to engineer against is the opposite case: the model had more to say, hit the ceiling, and the response was cut off. The API tells you this happened — stop_reason comes back as "max_tokens" instead of a natural end-of-turn — but only if your code looks.
The model's own ceilings
You cannot set max_tokens arbitrarily high; each model has a maximum output length:
| Model | Max output (synchronous Messages API) |
|---|---|
| Claude Fable 5 | 128k tokens |
| Claude Opus 4.8 | 128k tokens |
| Claude Sonnet 5 | 128k tokens |
| Claude Haiku 4.5 | 64k tokens |
Those values apply to synchronous requests; via the Message Batches API, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 5, and Sonnet 4.6 support up to 300k output tokens with the output-300k-2026-03-24 beta header. You can also read each model's limit programmatically — the Models API returns max_tokens per model — rather than hard-coding the table above.
Thinking tokens count against the same cap
On models with extended or adaptive thinking, the reasoning the model does before answering is billed as output and counts toward max_tokens — the cap is a hard limit on thinking plus response text combined. This is the most common source of surprise truncation on newer models: a request that comfortably fit its answer in 2,000 tokens starts hitting stop_reason: "max_tokens" once the model decides the problem deserves serious thought. The documented remedies are to raise max_tokens or lower the effort level. At high effort settings on Opus-class models, Anthropic suggests a large cap — 64k is the documented starting point for xhigh and max effort on Opus 4.7/4.8.
Why generous caps are cheap
Teams often set max_tokens low out of caution about rate limits or cost. Two facts change that calculus. First, output-tokens-per-minute rate limits count only tokens actually generated, in real time — max_tokens itself does not factor into rate-limit accounting, so a high cap has no rate-limit downside. Second, billing works the same way: an unused ceiling costs nothing. What a generous cap does expose you to is a single runaway response being longer (and pricier) than expected, so the right control is monitoring output length, not squeezing the cap until truncation appears.
max_tokens comfortably above the longest legitimate response you expect (with headroom for thinking), then treat stop_reason: "max_tokens" as an error signal in code — log it, alert on it, and retry with a higher cap where the use case allows.Interaction with the context window
Input and output share the model's context window, and max_tokens participates in the arithmetic. On Claude 4.5 and later models, a request whose input plus max_tokens exceeds the window is accepted, and generation simply stops early with stop_reason: "model_context_window_exceeded" — a third stop reason your handling code should recognize. Earlier models instead rejected such requests with a validation error unless a beta header was set. Input alone exceeding the window is always a 400 error on every model.
Truncation is worse than it looks with structured outputs
When you use structured outputs (output_config.format), a response cut off by max_tokens may be incomplete or invalid JSON — the schema guarantee cannot survive truncation. The official guidance is to retry with a higher max_tokens. If your pipeline parses model output mechanically, checking stop_reason before parsing is not optional. Two edge cases round out the picture: max_tokens: 0 is a special cache pre-warming request on the first-party API (it writes the prompt cache and returns empty content), and inside the Message Batches API every request must set max_tokens of at least 1.
Where to go next
Tuning the cap against reasoning depth is covered in thinking budgets and effort levels; the cost side lives in right-sizing max_tokens; and stop reasons catalogs every way a response can end.