model_context_window_exceeded behaviour

Definition

How the API behaves when a request would overflow the context window — either a 400 error (input alone too long) or a graceful stop (input + max_tokens overflow on 4.5+ models).

Key points

• Input alone exceeds the window: API returns 400 invalid_request_error ("prompt is too long") on every model.
• Input + max_tokens exceeds the window (Claude 4.5 models and newer): the API accepts the request; if generation reaches the limit it stops gracefully with stop_reason: "model_context_window_exceeded".
• On earlier models that same case returns a validation error instead — opt into the graceful behaviour via beta header model-context-window-exceeded-2025-08-26.
• This is a distinct stop_reason value — handle it alongside end_turn, max_tokens, tool_use, pause_turn, refusal (see Stop reasons).

Why it matters for the exam

• Tests distinguishing the 400 "prompt is too long" (input overflow) from the graceful model_context_window_exceeded stop (output overflow on 4.5+), and knowing the beta header for older models.

Common gotchas

• Assuming overflow always errors — on 4.5+ models an output overflow stops gracefully, it does not 400.
• Confusing the two cases: input-alone overflow always 400s; input+max_tokens overflow is the graceful/stop path.
• Older models need the beta header to get the graceful behaviour.

See also

• Stop reasons
• Context Windows By Model
• Context Awareness
• Server-side Compaction

Sources

• docs-models-pricing
• netlight-study-guide