API Error: Usage credits required for 1M context

The request was refused because the account behind it is not enabled for the 1M token context tier. That is a capability gate, not an exhausted allowance: you have not used anything up, no clock is running down, and nothing resets at midnight. It is also not an empty prepaid balance — that condition prints Credit balance is too low — and it is not a full context window, which prints Prompt is too long. The part that surprises people is the part worth saying first: you almost certainly never asked for a 1M-token window. The tool asked for it on your behalf.

Data as of 2026-09. Vendor limits and defaults change; check the official docs for current values before acting on any number below.

Who decided this request needed a million tokens

Several current Claude models carry a 1M-token context window — Opus 5, Sonnet 5 and Fable 5.1 are all listed at 1M, while Haiku 4.5 is 200K. When you are signed in to a claude.ai plan, having a model that can run at 1M and being entitled to run it there are two separate things, and the second one is what this message is about.

The mechanical piece that makes this confusing is the auto-compact window. On models running with a native 1M window, Claude Code’s default is to compact before the window fills, at about 967K tokens. Models running with a 200K window compact at the 200K boundary instead. So on a native-1M model with default settings, nothing stops the conversation at 200K — the tool is configured to let it grow almost to a million before it intervenes. The first request that crosses out of standard context is the one that trips the gate, and by then you are several turns past the decision point with no visible warning that a boundary was approaching.

That is the non-obvious part: the threshold that puts you into the gated tier is a client-side default you can change, not a property of your prompt. Setting CLAUDE_CODE_DISABLE_1M_CONTEXT=1 makes native-1M models compact at 200K, which keeps every request inside standard context. That costs nothing, requires no billing change, and is the correct answer for most people who hit this once and do not actually need a million-token conversation.

The word “credits” is doing three jobs at once

Four different money-shaped things can stop a Claude Code request, and they are told apart by the wording, not by your intuition about which one you have.

Usage credits — extra usage bought on top of a claude.ai plan. /usage-credits buys them on Pro and Max, or requests them from an administrator on Team and Enterprise. It is not available at all with API key authentication. This is the thing the error names.
Console prepaid credits — a balance on an API account. Exhausting it prints Credit balance is too low, a different message with a different fix. Buying these does nothing for the error on this page.
A plan allowance — You've hit your session limit · resets 3:45pm and its weekly and per-model-family variants. These name a reset time. This error does not.
A spend limit — You've hit your monthly spend limit · raise it at claude.ai/settings/usage and the individual, org, team and channel variants. These are money caps you or an administrator set, and they say “spend” or “usage limit”, not “usage credits”.

/status shows which credential is actually active, and it answers this in one line. If it reports an API key where you expected your subscription, a stray ANTHROPIC_API_KEY in the environment is routing you somewhere you did not intend — and on that path /usage-credits is not even offered, so no amount of clicking in the plan settings will change what the request sees.

One number this page deliberately will not give you: what a 1M-context request costs once you enable it. The published per-model input and output prices are base rates, and whether long-context requests are priced against them or against a surcharge is not something to take from a third-party page. Check the vendor’s current pricing before you turn this on for a team.

Is retrying useful?

Yes — in the sense that the request itself is fine and needs no edits. Pressing up-arrow and Enter right now, unchanged, will fail identically.

The distinction matters because it determines what you do next. The blocking condition lives in account state, outside your process, and can change without you touching a single byte of the conversation: someone enables usage credits, an administrator approves a request, or the environment variable pointing at the wrong credential gets unset. The moment one of those happens, the same turn you already have goes through unmodified. That is not true of a malformed request, and it is why this is worth re-sending rather than rewriting.

What it is not worth doing is looping. There is no retry-after header here because this is not a throttling response, so there is no interval to honor and no backoff schedule that terminates. Claude Code already retries transient failures up to ten times with exponential backoff before showing you anything — that is the CLAUDE_CODE_MAX_RETRIES default — and while it does, it prints a Retrying in Ns · attempt x/y line. An error that appeared instantly, with no retry line in front of it, was never on the retry path. Take that as confirmation that the condition is deterministic and go change something.

Which situation is yours

Each of these has an observation that selects it, not just a description.

/status names an API key rather than your subscription — you are on the API path. Unset ANTHROPIC_API_KEY in the shell, the shell profile, and any editor or launcher that injects environment variables, then re-check /status before doing anything else.
/status names your subscription and the conversation is long — this is the ordinary case. The conversation grew past standard context and the tool requested the larger window.
It fires on a short, fresh conversation — the conversation is not what pushed you over. Run /context and read which categories occupy the window: system prompt, tool definitions, attachments and MCP tool schemas all load before your first message, and a large MCP surface can put a brand-new session well past 200K on its own.
It started after you switched models — /model changes which context window is in play. A model with a 200K window cannot ask for the gated tier at all; a native-1M model can and will.
It fires during /compact rather than during a normal turn — that is a different failure with a different escape route, covered on the compaction variant of this error.

Fix, keyed to the case above

You do not need a million-token conversation — set CLAUDE_CODE_DISABLE_1M_CONTEXT=1 so native-1M models compact at 200K, or set the auto-compact window explicitly with /autocompact <value> (which writes the autoCompactWindow user setting), the --autocompact launch flag, or the CLAUDE_CODE_AUTO_COMPACT_WINDOW environment variable, in increasing order of precedence. The accepted range is 100K to 1M tokens, and the environment variable accepts only a plain count.
You do need it — turn on usage credits for the account, or use /usage-credits to buy them on Pro and Max, or to send the request to an administrator on Team and Enterprise. Decide on the cost first; see the pricing caveat above.
Wrong credential — fix the environment, not the billing. Buying anything before /status reads what you expect is how people end up paying twice for the same work.
Nothing in the conversation is worth keeping — /clear starts a new window and the old conversation stays reopenable with /resume. This is the cheapest exit and the one people skip because it feels destructive.
You are on a model you did not choose deliberately — switch with /model. Note that each model has its own prompt cache, so the next request re-reads the whole conversation uncached.

Confirming it actually cleared

Re-send the exact turn that failed, unmodified. It should succeed with no edits at all — that is the point of the test, because if it only works after you also shortened the prompt, the gate was not what stopped you and something else is failing underneath.

Then check the setting you changed rather than trusting the silence. If you capped the window, /context should show the conversation sitting below the new boundary and a compaction should fire there rather than hundreds of thousands of tokens later. If you enabled usage credits, /usage shows the plan windows, and the first thing to watch is whether the work you are doing is now drawing on paid extra usage every session — a gate that stops firing because you are paying past it is a resolved symptom, not a resolved problem.

If the message is about a balance rather than a capability — credit balance too low, delivered as a 400 — the fix is on the billing side and the diagnostic order is reversed. If you are being throttled instead of gated, four different limits print the same rate-limit line and the presence of retry-after decides whether waiting helps. And if the real problem is that the conversation no longer fits anywhere, prompt is too long is the page for the window itself rather than for who may use it.

Before you enable paid extra usage on a whole team’s accounts, the Claude Code usage limit calculator is the faster way to find out whether your sessions are anywhere near needing a million-token window in the first place.