How to Fix “max_tokens: … which is the maximum allowed number of output tokens” in the Anthropic API
Every Claude model has its own output ceiling. Ask for one token more and the API refuses the whole request before it starts.
On this page
- The fix at a glance
- Read the 2 numbers first
- 1. Lower max_tokens to the model's ceiling
- 2. Clamp it in code, per model
- 3. Stream anything with a large max_tokens
- 4. Make the thinking budget fit inside max_tokens
- 5. Find the default you didn't set
- 6. Use Message Batches for very long outputs
- Which fix to reach for
- Match your symptom to the fix
- When it still fails
Your code worked yesterday. Today you switched models, or bumped max_tokens for a longer answer, and every call fails instantly with a 400. In Python the SDK raises anthropic.BadRequestError, and the message looks like this:
max_tokens: 128001 > 64000, which is the maximum allowed number of output tokens for claude-opus-4-5-20251101
That exact string is quoted from a Claude Code bug report, not from Anthropic's docs. The docs don't print the message text, so treat the wording as what people have seen rather than a contract. The shape is consistent, though. It's your number, a >, the model's ceiling, and the model ID. Nothing was generated and nothing ran. The API checked one parameter and stopped.
#The fix at a glance
| What you see | Likely cause | Fix |
|---|---|---|
max_tokens: X > Y, which is the maximum allowed number of output tokens for ... |
You asked for more output than this model allows | Lower max_tokens to Y or less |
| Same error right after a model switch | Your ceiling was right for the old model | Look up the new model's limit |
| Same error from a framework or CLI you didn't configure | A default inside the tool is too high | Set its output-token option yourself |
A 400 about budget_tokens |
Thinking budget doesn't fit inside max_tokens |
Section 4 |
prompt is too long |
Input alone is over the context window | A different problem, see the end |
#Read the 2 numbers first
The message gives you everything you need. The first number is what you asked for. The second is the most this model will produce in one synchronous call. The model ID at the end tells you which limit applied, and that matters more than it sounds.
I always check that ID before I touch anything else. Half the time it isn't the model I thought I was calling. A config file, an environment variable or a framework default picked something else. If the ID is wrong, lowering max_tokens hides the real bug.
The raw response is a JSON body with "type": "error" at the top, and an error object with a type and a message. Here the type is invalid_request_error. Anthropic's errors page also notes there's a request_id on the response. Log it, because support will ask for it.
#1. Lower max_tokens to the model's ceiling
This is the fix in most cases. The ceilings below are from Anthropic's models overview as of 21 November 2026, and they're the synchronous Messages API limits.
| Model | Max output | Context window |
|---|---|---|
| Claude Fable 5.2, Opus 5.5, Sonnet 5.5, Haiku 5.5 | 128K | 1M |
| Claude Opus 5, Sonnet 5, Opus 4.6 to 4.8, Sonnet 4.6 | 128K | 1M |
| Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, Sonnet 4 | 64K | 200K |
| Claude Opus 4, Opus 4.1 | 32K | 200K |
Note the jump between generations. Code written for a 128K model will fail on every 4.5-generation model, because they stop at 64K. That's exactly what the bug report above shows. Something asked for 128,001 tokens, and Opus 4.5 allows 64,000. A second report shows the mirror case on Opus 4.6. It asked for 128,001 against a ceiling of 128,000, and was off by exactly 1.
Don't set max_tokens to the ceiling by reflex, either. It's a cap, not a target, so the model doesn't write more because you allowed more. A large value does change how the SDK treats the call, though, which is section 3.
#2. Clamp it in code, per model
If your app can call more than one model, hard-coding one number will break the next time you switch. I'd rather keep a small table and clamp every request against it. It's a few lines, and it turns a crash into a quietly shorter limit:
MAX_OUTPUT = {
"claude-opus-5-5": 128_000,
"claude-sonnet-5-5": 128_000,
"claude-haiku-5-5": 128_000,
"claude-sonnet-4-5": 64_000,
"claude-haiku-4-5": 64_000,
}
def safe_max_tokens(model, wanted, fallback=32_000):
return min(wanted, MAX_OUTPUT.get(model, fallback))
The fallback is the important part. An unknown model gets a conservative number instead of your largest one. If you'd rather fail loudly, raise an error there instead. Either is better than finding out from a 400 in production.
Keep the table next to your model config, not in a helper nobody reads. You'll update both at the same time, and you want that to be obvious. Check it against the models page whenever you add a model, because the ceilings change between generations.
#3. Stream anything with a large max_tokens
A valid but large max_tokens causes a different failure, and it's easy to confuse with this one. Anthropic's errors page says the SDK checks that non-streaming Messages requests aren't expected to run past a 10-minute timeout. A big enough max_tokens on a non-streaming call trips that check, and the SDK refuses the request on your side.
The page's advice is plain: avoid setting a large max_tokens without using streaming or the Message Batches API. Some networks drop idle connections, so a long silent request can die even when the API is fine. Streaming keeps bytes moving.
In Python you don't have to rewrite your handling. Open the stream and call get_final_message() on it. You get the same message object at the end, so the rest of your code stays the same. If you only change 1 thing for long outputs, change this.
#4. Make the thinking budget fit inside max_tokens
Older thinking requests carry a second number that has to fit. With manual extended thinking (thinking set to enabled with a budget_tokens value), Anthropic's docs say the budget must be less than max_tokens. The minimum budget is 1,024 tokens. Thinking tokens are a subset of max_tokens, so your budget also has to leave room for the answer itself.
A Claude Code bug report quotes the error as max_tokens must be greater than thinking.budget_tokens. That report is a user thread, so match on the meaning rather than the exact text. The fix is the same either way. Lower the budget, or raise max_tokens without passing the model's ceiling.
There's a bigger change here. Manual extended thinking with budget_tokens is deprecated, and Anthropic's docs say Claude 4.7 and later models reject it with a 400. On those models you switch to adaptive thinking (the model decides how much to think) with an effort setting. If you upgraded models and kept an old thinking block, that's another 400 that looks like a token problem.
#5. Find the default you didn't set
A lot of these errors come from code you didn't write. Frameworks, gateways and CLIs set their own max_tokens default, and that default was usually picked for one model. When you point the tool at another, the default can overshoot. The Claude Code reports above are exactly that. The tool asked for more than the model allowed, and the user hadn't set anything.
Search your config for the tool's output-token setting and set it explicitly. Look for names like max_tokens, maxTokens or a MAX_OUTPUT_TOKENS environment variable. Then rerun the same request. If the number in the error changes, you've found the right knob.
Cloud platforms deserve a check of their own. Bedrock and Vertex AI publish their own model pages, and their limits and headers have differed from Anthropic's API in the past. A 2024 Vertex AI forum thread shows an older Sonnet capped at 4,096 output tokens without a beta header. Check the platform you're actually calling, not just Anthropic's table.
#6. Use Message Batches for very long outputs
Sometimes you really do need more than 128K tokens back. The models overview has a footnote for this. On the Message Batches API, several current models support up to 300K output tokens with the output-300k-2026-03-24 beta header. The footnote lists Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Haiku 5.5, Opus 4.6 to 4.8 and Sonnet 4.6.
That limit doesn't apply to the synchronous API. Send the same max_tokens to a normal Messages call and you'll get this error again. Batches suit work that can wait, like bulk document generation. If your user is watching a spinner, split the job into sections instead. You'll often get better output that way too.
#Which fix to reach for
| Approach | Stops the 400 | Survives a model switch | Effort |
|---|---|---|---|
| Hard-code a lower number | Yes | No | Lowest |
| Clamp per model in code | Yes | Yes | Low |
| Message Batches with the 300K header | Yes, on listed models | Only on listed models | Medium |
| Split the task into smaller calls | Yes | Yes | Medium to high |
#Match your symptom to the fix
| You see | Go to |
|---|---|
X > Y and the model ID is the one you meant |
Section 1, then section 2 |
X > Y and the model ID surprises you |
Your model config, then section 5 |
An error that mentions budget_tokens |
Section 4 |
| The SDK refuses a long non-streaming call | Section 3 |
| You need more than 128K tokens of output | Section 6 |
#When it still fails
First, confirm the request you think you're sending is the one going out. Log the final request body right before the call, after every wrapper has added its defaults. I've lost more time to a stale config than to any API behaviour. In most cases the logged max_tokens is higher than the one in your code.
Then separate this error from its neighbours. On Claude 4.5 models and newer, Anthropic's context-windows page says the API accepts input plus max_tokens above the context window. If generation then reaches the limit, it stops with stop_reason: "model_context_window_exceeded" instead of failing. Earlier models returned a validation error for that. A third-party report quotes it like this:
input length and `max_tokens` exceed context limit: 198157 + 21333 > 200000, decrease input length or `max_tokens` and try again
And if the input alone is over the window, you'll get prompt is too long on every model.
If none of that fits, send the request_id to Anthropic support. Include the model ID and the exact max_tokens you sent.
For the input side of this problem, the context length guide covers trimming history and counting tokens before you send. If the request gets through but fails with a 529, that's capacity, not your parameters. See the Anthropic 529 overloaded guide.
Frequently asked questions
What does "max_tokens: 128001 > 64000" mean?
You asked for 128,001 output tokens and the model you called allows at most 64,000 in one synchronous request. The API rejects the request with a 400 invalid_request_error before generating anything. Lower max_tokens to the second number or below.
What is the max_tokens limit for Claude models?
It depends on the model. As of November 2026, Anthropic's models overview lists 128K output tokens for the current 5.x models, Opus 4.6 to 4.8 and Sonnet 4.6, 64K for the 4.5 generation and Sonnet 4, and 32K for Opus 4 and 4.1. Check the models page for the model you call.
Does a higher max_tokens make Claude write longer answers?
No. max_tokens is a ceiling, not a target. The model stops when it's done, or when it reaches the ceiling, whichever comes first. A very large value does affect how the SDK handles non-streaming calls.
Can I get more than 128K output tokens from Claude?
Not from the synchronous Messages API. On the Message Batches API, several current models support up to 300K output tokens with the output-300k-2026-03-24 beta header, per Anthropic's models overview.
Why does input plus max_tokens over the context window not fail any more?
On Claude 4.5 models and newer, the API accepts the request and stops generation with stop_reason model_context_window_exceeded if it reaches the window. Earlier models returned a validation error instead. If the input alone exceeds the window, you still get prompt is too long.
Written by
Vemuri Abhiram
Founder & Editor
Vemuri Abhiram is the founder and editor of Underread, where he writes about AI tools, software, and practical technology. He covers hands-on tool reviews, detailed guides, product comparisons, and emerging technologies.
You might also like
How to Fix “Invalid schema for response_format” in OpenAI Structured Outputs
Why OpenAI rejects a JSON Schema that looks valid, how to read the context path in the error, and the 6 fixes in the order they usually apply.
Vemuri Abhiram10 min read
How to Fix “CUDA out of memory” When Running a Local LLM
Why a model that loaded yesterday runs out of VRAM today, and the 5 fixes in the order that costs you the least quality.
Vemuri Abhiram6 min read
How to Fix “The requested webhook is not registered” in n8n (404)
Why an n8n webhook works while you watch it and 404s afterwards, and the 5 causes ranked by how often they're the answer.
Vemuri Abhiram5 min read
More from Underread, once a week.
The guides worth reading and the tests worth trusting. One email, every Friday.
No spam. Unsubscribe in one click.

