Claude Code · AI costs · 2026-10-17

Claude Code "You've hit your monthly spend limit": what it means and what to do

Claude Code has stopped with "You've hit your monthly spend limit", or with a message saying usage credits are required. This post explains whose limit it is, how to raise it or wait it out, why it can appear while your plan still seems to have usage left, and what usage credits cost.

This guide pairs with Spend Caps Kit, and if you want the next step, read Prompt caching not working? Check it in OpenAI and Anthropic (Next.js).

What we did and didn't test. We don't have a Claude plan, and we haven't bought usage credits or seen these messages ourselves. Everything below about messages, Settings > Usage, /usage and /usage-credits comes from Anthropic's docs and Help Center as of 17 Oct 2026 (listed in Sources). Plans, prices and limits can change, so check those pages before you rely on a detail here. We aren't affiliated with or endorsed by Anthropic or OpenAI; Claude and Claude Code are Anthropic's trademarks, and other product names belong to their owners; all are used here only to name those products.

What the message means

As of 17 Oct 2026, per Anthropic's error reference: "Your plan’s included usage can’t cover this request, and the usage credits that would otherwise pay for it have reached a spend limit."

The same page says: "That happens when one of your plan’s usage windows has run out, or when the request is one that only usage credits pay for, such as a request to a model that bills to usage credits."

So two things are true at once: your included usage didn't cover the request, and the usage credits that could have paid for it are capped.

Whose limit is it?

The error reference says the wording of the message tells you whose limit stopped you, and the text after the · says how to get it raised. Here is our summary of the variants listed there as of 17 Oct 2026:

Whose limit is it?
Message starts with	Whose limit	Who can raise it	Can you wait it out?
"You've hit your monthly spend limit"	Yours (Pro or Max)	You	Only if the message names a reset time
"You've hit your individual spend limit"	A per-member limit on your org	An admin	Only if the message names a reset time
"You've hit your org's monthly spend limit"	Your organization's	Someone who manages billing	Only if the message names a reset time
"You've hit your team's shared budget"	A pooled budget for a group you're in	An admin	Only if the message names a reset time
"You've hit your channel's monthly spend limit"	One Slack channel's budget	An org owner or channel manager	Only if the message names a reset time
"spend limit reached" (lowercase)	A Claude apps gateway operator's cap	The gateway operator	Until the period it names resets

The full message for a Pro or Max subscriber, per the docs, looks like this:

You've hit your monthly spend limit · raise it at https://claude.ai/settings/usage?from=cc_cli_limit_message

And for an organization limit:

You've hit your org's monthly spend limit · visit https://claude.ai/admin-settings/usage to raise it

A few details from the same page, in our words: the team's shared budget message doesn't name the group; a channel's limit covers only that one channel, so your organization may still have budget elsewhere; and on organizations with usage-based billing the message can say "usage limit" in place of "spend limit". On the lowercase variant, the docs say: "If you connect through a Claude apps gateway and see lowercase spend limit reached, that is your gateway operator’s cap instead".

Raise it, or wait it out

The error reference lists these steps as of 17 Oct 2026. We haven't been able to try them.

Pro and Max: raise your monthly spend limit in Settings > Usage on claude.ai, or run /usage-credits. The costs doc says that on Pro or Max, /usage-credits opens Settings > Usage on claude.ai in your browser.
Team and Enterprise: raise the limit in Organization settings > Usage if you manage billing, or ask an admin. The docs say /usage-credits sends that request to your admin for you.
A channel's limit: ask an org owner or the channel's manager to raise it on claude.ai.
Waiting: "When one of your plan’s windows is what ran out, the message also says when that window resets, for example · your session limit resets 3:45pm, and access returns then without anyone raising the limit."

To see your plan's windows and when each one resets, the error reference points you to /usage.

"But my plan still has usage left"

This is a common point of confusion. Anthropic's docs give two documented reasons the message can appear while your session or weekly allowance still has room:

The request is credit-only. As quoted above, some requests are ones "that only usage credits pay for, such as a request to a model that bills to usage credits." If your credits are capped, that request is blocked even with plan usage left.
The 1M-context check. Covered in the next section.

If neither fits what you're seeing, there are open reports on GitHub from users describing similar situations, for example here, here and here. We haven't verified them and can't say what causes them; following or adding to those threads may be the most direct route to an answer.

"Usage credits required for 1M context"

A related message, from the same error reference:

API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

The docs describe it this way: "This is an entitlement check, not a quota exhaustion. It fires even when your session and weekly allowances have capacity remaining."

The message itself gives the two options: switch back to standard context with /model, or turn usage credits on with /usage-credits and restart Claude Code.

What usage credits are and what they cost

The costs doc puts it simply: "Usage credits let you keep working past your plan’s usage limit." From the Help Center article on managing usage credits, as of 17 Oct 2026:

Price: "Usage credits are billed at standard API rates; see our pricing page for details."
Billing: "Usage credits are charged separately from your paid Claude subscription and appear as additional charges on your bill."
When they stop: "Your usage continues until you reach your monthly spend limit, or your balance runs out with auto-reload off."
Controls: the article lists a monthly spending cap, auto-reload when your balance drops below a threshold you set, and usage alerts as you approach your limits.
The switch-over: "If usage credits are enabled and you have funds available, your next request goes through on usage credits and the notification changes to “Now using credits.”"
Resets: "Usage credits don’t affect the reset timing of any of these limits."
Expiry: "In most cases, usage credits do not expire." The same article names an exception: in certain jurisdictions, such as Japan, usage credits expire six months after purchase, starting 10 Sep 2026.

To check what you've spent, the costs doc says /usage shows a usage-credits row while credits are on; on Pro and Max it shows your spend for the month against your monthly spend limit, or "Unlimited" with no spend figure if you haven't set one.

What could a credit-billed session cost? A worked example

This is an estimate at standard API rates, not your bill. It uses the Anthropic list prices in our AI API cost calculator as of 17 Oct 2026, for Claude Sonnet 5.5, with token counts we made up for illustration:

2,000,000 cached input tokens read at $0.10 per million: $0.20
200,000 uncached input tokens at $2.00 per million: $0.40
300,000 tokens written to the five-minute cache at $2.50 per million: $0.75
50,000 output tokens at $10.00 per million: $0.50

That comes to about $1.85. Real sessions vary widely with model, context size and how often the cache misses, so don't treat this as typical. Put your own numbers into the calculator.

What doesn't count

Max's monthly API credits. The Help Center says "Usage credits are separate from the monthly API credits included with Max plans." The Pro or Max plan article adds: "Monthly API credits included with Max plans can’t be used in Claude Code or the Claude apps, including for extra usage."
API key sign-in. The costs doc says /usage-credits is for claude.ai subscription sign-in, and "the command isn’t available with API key authentication."

Keep credit spend down

Mind the cache lifetime. The costs doc says: "The lifetime is an hour on a subscription and drops to five minutes once you’re drawing on usage credits". A break longer than the lifetime can mean re-sending your full context. Our prompt caching post explains why cache misses cost more.
Update Claude Code. The 2.1.302 changelog entry (16 Oct 2026) reads: "Fixed prompt suggestions spending usage credits on models your plan pays for only with credits: they are now skipped after a reply billed to credits".
Make your plan last longer. Our post on reducing Claude Code token usage covers habits that can help.

If you also use Codex or Cursor, see Codex credits and resets and Cursor usage limits.

FAQ

Why does it say monthly spend limit when my plan has usage left? Anthropic's docs give two reasons: the request may be one that only usage credits pay for, or it may be the 1M-context entitlement check, which can fire while your session and weekly allowances have room.

Do Max monthly API credits pay for Claude Code usage credits? No, per Anthropic's Help Center as of 17 Oct 2026: Max's monthly API credits can't be used in Claude Code or the Claude apps, including for extra usage.

Can I wait instead of raising the limit? If the message names a reset time for one of your plan's windows, the docs say access returns then without anyone raising the limit.

Do usage credits expire? Per Anthropic's Help Center as of 17 Oct 2026: "In most cases, usage credits do not expire." In certain jurisdictions, such as Japan, they expire six months after purchase, starting 10 Sep 2026.

Building your own AI app? Give your users the same kind of cap

Anthropic gives subscribers a monthly spend limit, per-member limits and pooled team budgets. If your own Next.js app calls Anthropic or OpenAI for your users, you may want similar controls for them. Our per-user spend limits post shows the pattern, and for API-side 429s see our rate limit error guide.

Disclosure: this is our own paid product. The Spend Caps Kit is designed to add per-user rate limits and a monthly dollar cap per user to your own Next.js app. It does not change Claude Code limits, usage credits or spend limits. It does not track or cap your Claude subscription or usage-credit spend. It does not replace Anthropic Console spend limits. It costs $19 (plus VAT where applicable).

Sources (checked 17 October 2026):