Context window exceeded: a practical diagnostic checklist

When a request fails with context_window_exceeded or a similar message, do not start by buying more credits or repeatedly retrying the same payload. Establish which layer produced the message, whether any output was generated, and which input/output limit was reached. Then change the specific part of the request responsible for the failure.

This is a cross-provider troubleshooting method, not a claim that all providers use the same error code. Preserve the exact code from your own response. Documentation checked September 5, 2026. All token allocations and incident examples below are synthetic; they illustrate diagnostic reasoning without asserting a current model's maximum capacity.

Classify the failure before changing anything

Evidence	Likely category	First useful action
The input itself exceeds the documented window	Oversized request	Measure and reduce request content
Output exists and a context stop reason appears	Generation reached available room	Review partial output and reserve space
HTTP 429 or an explicit rate message	Rate or throughput limit	Inspect that provider's limit and retry policy
A subscription usage/reset message	Account allowance	Check the account's period and entitlement
The client fails before an upstream request	Client-side capacity assumption	Inspect client model configuration

A status code alone is not a full diagnosis. Read the structured response fields and distinguish the upstream provider's message from wording rewritten by a gateway. Keep a sanitized record of endpoint host, exact model identifier, client version, status, error type, and relevant token totals. Do not share authorization headers, prompt bodies, private repository files, or customer documents in a public bug report.

Recognize input rejection versus output stopping

The current Claude API context documentation distinguishes an input that is already too long from generation reaching the window boundary. It documents a 400 invalid_request_error for the former and a model_context_window_exceeded stop reason for the latter on supported models. Exact behavior is model-dependent, so inspect the current reference for your selected model rather than assuming every boundary produces an HTTP error.

This distinction matters for recovery. If no valid response was produced, the next step is a corrected request. If the model produced part of an answer, first decide whether that partial answer is safe to use. Do not execute a truncated configuration, apply a half-finished patch, or accept incomplete structured data as though normal completion had occurred.

Step 1: reproduce with a minimal, harmless request

Send a short non-sensitive test through the same endpoint and model configuration. If it succeeds, you have evidence that basic routing works. If it fails too, inspect authentication, model availability, and compatibility before optimizing a giant prompt. Keep the test bounded; the goal is to isolate the failure, not generate a benchmark report.

For a coding client, try a small sample repository rather than clearing or modifying the real project. Do not delete conversation history or working files as a reflex. Preserve the useful state in a short local handoff before trying a fresh session. Recovery should not turn a context problem into a data-loss problem.

Step 2: inventory the actual request components

Write down the instructions, conversation history, attached text, retrieved results, tool definitions, images or documents, and desired output allowance. Count with the provider's supported method when available. A count made with an unrelated tokenizer is an estimate, and a plain-text word count ignores structured overhead and non-text inputs.

In a synthetic 16,000-token deployment, imagine 3,000 instruction tokens, 8,000 document tokens, and 4,000 historical tokens. You have already used 15,000 before generating the next answer. Asking for a substantial 3,000-token response is incompatible with that planning budget unless content is reduced or a verified larger deployment is selected. Merely shortening the final question by ten words does not address the dominant components.

Step 3: make the smallest meaningful reduction

Remove an unrelated document or replace a repetitive log with the relevant error and surrounding context. Keep identifiers and source references that allow the evidence to be retrieved again. Re-run the same task and compare the error category. This one-change approach makes the result interpretable: you can tell whether reducing that component changed the outcome.

For multi-document work, split by an actual subquestion. Ask for a structured summary of each relevant section, retaining source references and unresolved conflicts, then combine those summaries in a final reasoning step. This is an editorial workflow proposed here, not an automatic provider guarantee. Verify that the split has not hidden a cross-document dependency needed for the answer.

Do not remove safety instructions, the required output schema, or the acceptance criteria simply because they occupy space. The purpose is to finish the right task within the constraint. A smaller request that loses essential requirements can produce a valid API response and still fail the user's goal.

Step 4: inspect the serving layer

With a local Ollama model, inspect the effective context allocation and hardware state rather than only the model's marketing page. With a gateway, verify the exact upstream model mapping and any request-size restriction the gateway adds. With an agent client, check whether the client assumes a different capacity from the backend. See Claude Code's context controls for that specific case.

Keep configuration changes reversible and narrowly scoped to the test. Document the old setting, the new setting, and the result. Raising an assumed client limit does not enlarge a server's capacity; raising a local context allocation can introduce a new memory problem. A successful correction must satisfy both the request contract and the serving resources.

Step 5: handle streams and partial usage honestly

Ollama's streaming error reference notes that an error can arrive after the response starts without changing its initial status. Read the complete stream outcome instead of treating HTTP 200 as automatic success. The usage reference puts completed metrics in the final chunk; an interrupted stream may leave a gap in your local ledger.

Record an interrupted attempt as incomplete and its missing usage as unknown. Do not quietly assign zero cost or assume the provider will charge the full reserved output. Reconcile with the account's actual records when you need an invoice-level answer. Our API accounting guide separates measurements, estimates, and unknowns.

Step 6: confirm the fix with an acceptance test

For a document task, check the required sections and source references. For code, inspect the diff and run the scoped test. For structured extraction, validate the complete schema, not only whether the first object parses. Save the now-working request shape and its measured token totals as a baseline.

Add a margin appropriate to your real workload rather than pushing every request to the observed boundary. A future tool result or a slightly longer document may change the size. If a job varies widely, preflight it and route oversize cases to a defined fallback. Bounded recovery is more predictable than an open-ended retry loop.

Frequently asked questions

Will adding money to my account fix this?

Not when the problem is request capacity. Account credit and context space solve different constraints. Identify a billing or allowance message before considering a spending change. The Ollama plan calculator compares cash scenarios; it cannot make an oversized request fit.

Does lowering the requested output always solve it?

No. It can help with a capacity plan that lacks output room, but it cannot repair input that already exceeds the available window. It can also truncate the useful result. Diagnose the input first and match the output allowance to the actual task.

Should I automatically retry this error?

Not unchanged. A deterministic size problem generally needs a smaller request, a corrected mapping, or a confirmed alternative capacity. Limit retries and log the reason for each changed attempt so operational cost does not disappear inside a retry loop.

Is the exact error spelling universal?

No. Different clients, providers, and gateways use different codes and messages. This page targets the general search phrase while preserving the specific Claude stop reason as an example. Always classify the structured evidence from your own endpoint.