“`stop_reason`: `model_context_window_exceeded`” — not your max_tokens, and not a turn cap

"stop_reason": "model_context_window_exceeded"

That value is Claude telling you which limit ended the response, and it is the one answer the three usual suspects cannot give you. Not your max_tokens. Not a turn cap. Not a timeout. The response ran into the model’s context window and stopped there, and because the request succeeded you get this as a field on an HTTP 200 rather than as an exception.

In ten seconds. Treat the response as truncated — it is valid, it is incomplete, and if it was generating JSON or a tool call that JSON is cut off.

Raising max_tokens will not help, because max_tokens is not what stopped it. On older models you may not see this value at all unless you ask for it: the documented beta header is model-context-window-exceeded-2025-08-26, and on Sonnet 4.5 and newer the API returns the value without one.

What the documentation says, quoted

From Stop reasons and fallback, the section headed model_context_window_exceeded:

Claude stopped because it reached the model's context window limit. This lets you request the maximum possible tokens without knowing the exact input size.

The second sentence is the part people miss, and it is a capability rather than a caveat. It means you are permitted to ask for far more output than you can prove will fit — set max_tokens high, let the window be the binding constraint, and read this value to learn that it was. The quick-reference row on the same page states the handling in six words: The response filled the model’s context window. — Treat the response as truncated.

The detail that decides whether you ever see it

This stop reason is currently typed only in the SDK's beta namespace, so the following examples call client.beta.messages and use the Beta-prefixed types. On Sonnet 4.5 and newer models the API returns this value without a beta header. For earlier models, add the model-context-window-exceeded-2025-08-26 beta header to enable it.

Three consequences, all of them things that change code you have already written. First, the value is typed in the beta namespace, so a strictly-typed handler built against client.messages may not have a case for it even though the string can arrive. Second, model choice decides availability: Sonnet 4.5 and newer return it plainly, earlier models need the header. Third — and this is the one that bites — if you are on an earlier model without that header, the response still gets truncated by the window. You simply receive a less specific stop reason for it, and you go looking for a turn limit that was never involved.

That is also why this page exists alongside max_turns vs timeout vs context window. That page is about reasoning your way to which of three limits fired. This one is about the field that just tells you, and about the two conditions — model and header — under which it will.

Truncated is not failed, and that is the trap

The documentation is explicit that this field lives on success: stop_reason “is part of every successful Messages API response. Unlike errors, which indicate failures in processing your request, stop_reason tells you why Claude completed its response generation.” So: status 200, no exception, a content array with real text in it, and a result that stops mid-sentence. A pipeline whose only check is try/except will write that straight into your database.

Where it hurts most is structured output. A truncated paragraph is obvious to a human reader. A truncated JSON object is not obvious to anything until a parser three stages downstream fails on an unterminated string, by which point the stop reason that explained it is long gone. The same holds for a cut-off tool call: your agent loop receives an assistant message whose tool input is unparseable and reports a tool error, which is a true statement about a symptom and a useless one about the cause.

What to do about it

Branch on the value before you use the content. The documentation’s own best-practice dispatch has a separate arm for this — case "model_context_window_exceeded": return handle_context_limit(response) — distinct from the max_tokens arm beside it, because the remedies are different.
Do not raise max_tokens in response to it. The window is the constraint. Raising the output budget cannot buy room that the input has already spent.
Shrink the input, not the ask. Shorter history, fewer or smaller tool results, retrieved passages instead of whole documents. A long-running agent loop grows its own input on every turn, which is why this stop reason tends to appear late in a run rather than at the start of one.
Record which model served the call. Availability of this value depends on the model, and in a scheduled system the model is not always the one you think — a run can be handed a smaller context window than the same run got yesterday without a line of your code changing.
Keep partial output. A truncated response contains real work. Persist it, mark it truncated, and make the mark visible to whatever reads it next.

One narrower note from the same page, worth having if you are raising output budgets to probe the window: the Python example carries the inline comment # Python SDK requires streaming for max_tokens above ~21k. If you set a large max_tokens to find the ceiling and the SDK objects before any request goes out, that is the reason, and it is a client-side constraint rather than anything the model did.

Provenance

One document, for this page: Stop reasons and fallback in Anthropic’s own API documentation — 2,208,588 bytes, HTTP 200, fetched 4 October 2026 for this page. We aimed at docs.claude.com and were redirected once, so the bytes quoted here were served by platform.claude.com; that is the host we read and the host we checked for permission before reading it. Every sentence shown in a quote block above is from that fetch. The page carries no publication or revision date of its own, so we do not give one. We did not read the Messages API reference, the SDK source, or any other page on that host, and nothing here describes them.

There is a written guide: the stop-reason dispatch above as a table you can hold against your own handler, what to shrink when the window rather than the output budget is the binding constraint, and how to keep a truncated response marked as truncated all the way through a pipeline instead of discovering it at a parser three stages downstream.

No page on this site has a checkout widget of its own. There is a written guide behind this host and it is on sale at $19 on a storefront that delivers the files automatically and carries a 30-day money-back guarantee: buy it there; the guide can also be paid for with 19 USDC on Base at the payment page, where delivery is by hand as a reply to your email. Every page on this site, including this one, is free to read in full, with no sign-up and nothing gated.

The short version: model_context_window_exceeded means the response hit the model’s context window, not your max_tokens and not a turn cap, so raising max_tokens changes nothing. It arrives on an HTTP 200 with real but truncated content — dangerous for JSON and for tool calls, which fail later and elsewhere. The value is typed only in the SDK’s beta namespace; Sonnet 4.5 and newer return it without a header, earlier models need model-context-window-exceeded-2025-08-26. Branch on it before you use the content, shrink the input rather than the ask, record which model served the call, and persist the partial output with the truncation marked.

Nearby

stop_reason: pause_turn — the sibling value on the same field: a server-side tool loop that hit its iteration limit and is resumed by resending rather than by raising anything.
max_turns vs timeout vs context window — the reasoning version of this question, for the many stacks that give you no field to read.
Why a scheduled agent run got a smaller context window than yesterday — how the model, and therefore the window, can change without your code changing.
Agent stopped after 50 turns and produced no output — the case where a cap, not the window, is what you are looking at.
Why an agent run dies before its timeout — the full set of ceilings that fire while the clock still has room.

This page counts anonymous readership, and it carries one counter rather than the two that the older pages on this host carry. Each load sends the page path, the address of the page you came from, how long the page was open, whether you scrolled, and any campaign or outreach code in the link you followed; a second “engaged” event is sent once, ten seconds after the page opens — whether or not the tab is in front of you — or as soon as you scroll a quarter of it. The campaign codes from the first link you arrived on are kept in this browser’s local storage, and a later visit that arrives with no codes of its own is counted against them; a link carrying its own codes is used for that visit, and the stored first touch is never replaced. An outreach code is removed from the address bar after it is read. Because this page sends one view event rather than two, a view count taken from it is directly comparable to a load, which is not true of the eighteen pages published before it — those send two, and any rate measured against them reads half its true value. No name is attached to any of this: the only identifier the code can send is an outreach token minted per recipient, and no link carrying one has ever been sent for this page. No cookie; the local storage above does that job. The page also asks this domain for an analytics script at /_vercel/insights/script.js; on 26 September 2026 that address returned HTTP 404 on every host we publish, so no script from another company was served or ran — the page goes on asking, so this stops being true the moment that address starts answering, without a byte of this page changing. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.

“stop_reason: model_context_window_exceeded” — not your max_tokens, and not a turn cap