[BUG] "Out of usage credits" message doesn't say which limit was hit — Max subscribers buy extra credits unnecessarily

[searayca]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Summary

I'm on a Max subscription. Tonight — for the third time — Claude Code told me "You've run out of usage credits" with no indication of WHICH limit was actually hit. The message does not distinguish between:

(a) the Max plan's included usage being temporarily exhausted (which resets on its own schedule at no cost),
(b) purchased extra-usage / API credits being exhausted, or
(c) a user-configured extra-usage spend cap being reached.

Because the wording implies the subscription itself has lapsed or that credits must be purchased, I upgraded/bought credits I did not need — $38 this time. This has now happened two or three times.

Why this matters

I'm a developer in the middle of focused sprints. When work stops with "you've run out of usage credits," the only thought pattern is "get credits back NOW." The message gives no reset time, no limit-type breakdown, and no signal that waiting (or adjusting a spend cap) would restore access for free. That ambiguity directly converts into unnecessary purchases — which then require refund requests.

Compounding problem: the lockout blocks asking Claude itself for help

When the limit is hit, I am completely blocked from talking to Claude — even though my subscription is still valid (the included usage may simply have timed out for the day). So the one assistant that could explain "which limit did I hit, do I actually need to buy anything?" is exactly what the lockout takes away. There is no low-cost or read-only path to ask for advice about the limit state, which leaves purchasing as the only visible way to get unblocked.

Related issues (not duplicates)

• [BUG] "Approaching usage limit" banner fires when user is not approaching any limit #51550 / "Out of usage credits" banner shown while session and weekly limits both have headroom #61125 — false-positive "out of usage credits" banner while limits have headroom (different bug: banner firing wrongly; this issue is about the message content being ambiguous when a limit IS hit)
• [Feature Request] Add direct link to billing/settings page when API spend limit reached #14363 (mine, closed not-planned) — requested a direct billing/settings link on the spend-limit message
• [BUG] Model selection not persisting - Max subscription triggers usage credits error for 1M context #65019 / [BUG] API Error: Usage credits required for 1M context #63060 — 1M-context "usage credits required" confusion on Max plans

What Should Happen?

The limit message should state explicitly: (1) which limit was hit — plan included usage vs. extra-usage credits vs. user-configured spend cap; (2) when it resets (absolute time + timezone); (3) whether any purchase is required at all, with explicit wording like "Your Max subscription is still active — no purchase is needed; usage resets at " when it's a plan-limit reset; and (4) a link to the usage/billing page showing the relevant bucket. Additionally, hitting a usage limit should not produce a total lockout with purchase as the only visible exit: a subscriber in a limit-hit state should still be able to ask a minimal question about their limit/usage state (or at minimum see a self-serve explainer of exactly which bucket is exhausted and what restores access for free).

Error Messages/Logs

Steps to Reproduce

1. Use Claude Code on a Max subscription during a heavy-usage development sprint.
2. Exhaust a usage limit (the plan's included usage, or a configured extra-usage spend cap).
3. Claude Code stops with a message along the lines of "You've run out of usage credits."
4. Observe that the message does not say which limit was hit (plan usage vs. extra-usage credits vs. spend cap), does not show a reset time, and does not say whether a purchase is required — the natural reading is that you must buy credits/upgrade to continue.

Claude Model

None

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

2.1.173 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response

[github-actions]

Found 3 possible duplicate issues:

1. [Bug] Misleading error message: Rate limiting shown as monthly usage limit #53586
2. [BUG] You've hit your org's monthly usage limit #52908
3. [BUG] Usage display shows 28% weekly but session is blocked — numbers don't reflect actual limit #66180

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[yurukusa]

The three-way ambiguity you describe is real, and naming the three layers precisely helps others avoid the same unnecessary purchase:

1. Plan-included usage — your Max subscription's rolling usage window. When this is what's exhausted, it refills on its own schedule at no cost. This is the layer where "buy credits" is the unnecessary purchase you hit.
2. Purchased / extra-usage credits — real money at standard per-token API rates, only consumed after you've explicitly enabled extra usage and the plan window is exhausted.
3. A spend cap you configured — a ceiling you set, not an exhaustion.

The practical self-check before buying anything: open /usage (and the console billing page if you have access). The single tell is whether a reset time is shown for the limit you hit. If there's a reset time, it's layer 1 — waiting costs nothing, and buying credits is unnecessary. If the "what's contributing" breakdown points to extra-usage credits instead, it's layer 2/3. That reset-time vs. extra-usage distinction is what separates "just wait, free" from "this is real spend."

(I can't see the server-side billing internals, so treat that as how to read the surfaces you already have — not a claim about what the message should say. Your core request, that the message name which limit was hit, is the right fix.)

One time-sensitive note for anyone landing here from search: from 2026-06-15, programmatic use (claude -p, the Agent SDK, GitHub Actions) moves to a separate credit pool from interactive use. That adds a fourth thing this "out of usage credits" message will need to disambiguate. If you mostly use Claude Code interactively in the terminal/IDE, that interactive usage stays on your subscription — but the "which limit did I actually hit?" ambiguity you've run into is about to get one layer deeper, so checking the reset time before reflexively buying credits matters even more after the 15th.

[un-akzkn]

Adding another data point for this (observed 2026-07-20 JST, Claude Code v2.1.215):

/usage showed remaining quota for Fable (claude-fable-5) on my account, while at the same time a different session on the same account was prompted to purchase extra usage credits.

This looks like the same root ambiguity described in the OP, plus a possible display/enforcement mismatch: whatever limit the credit prompt was enforcing, it was not the one /usage displays — or the two were out of sync. Because the prompt doesn't say which limit was hit (nor that /usage disagrees), there is no way to tell whether buying credits is actually necessary before paying.

Suggestion: the extra-usage prompt should name the specific limit that was hit and show the same numbers /usage shows, so users can reconcile the two before spending money.

[un-akzkn]

Follow-up to my report above: re-authenticating with /login resolved it. After logging in again, the credit-purchase prompt stopped and quota state matched what /usage displayed.

So in my case the mismatch appears to have come from a stale/desynced auth or entitlement state on the client side, not from the quota itself being exhausted. Leaving this here because it reinforces the OP's point: the prompt gave no way to distinguish "your quota is actually gone" from "this client's session state is stale" — and the fix (re-login) is not something the message hints at.

Suggestion in addition to naming the limit that was hit: if the client's cached entitlement state is older than some threshold, the prompt should suggest re-authenticating before offering to sell credits.

[COOLak]

Adding a sanitized related signal because this issue captures the same dangerous ambiguity around usage-credit prompts and the actual limit being enforced.

Your report is about "out of usage credits" messaging that does not distinguish plan-included usage, purchased extra-usage credits, or a configured spend cap, causing users to buy credits unnecessarily. My direct case is a different Claude billing surface: manual prepaid / bulk usage-credit purchases fail or fail to commit, while automatic usage-credit reloads on the same paid billing setup continue charging successfully.

The overlap is the important part: plan-included usage, extra-usage credits, spend caps, model/session entitlement gates, auto-reload charging, manual purchase/commit state, and the visible credit ledger can diverge. When the UI cannot say whether buying credits is necessary, and when manual prepaid purchase itself can fail while auto-reload charges work, this needs entitlement + Billing Platform reconciliation rather than generic restart, card-decline, or top-up guidance.

Requested triage path: please route this class of issues to a human owner who can inspect plan/session quota evaluation, spend-cap evaluation, usage-credit ledger state, auto-reload triggers, manual purchase/commit state, and the exact CLI/web copy shown before users spend more money.

Privacy-sanitized public evidence hub for my related case:
https://coolak.github.io/anthropic-claude-billing-incident/

I am intentionally not posting card details, bank names, payment IDs, invoice IDs, support IDs, screenshots, raw logs, payment URLs, or private support-thread text here.

Additional public owner map / reconciliation matrix:
https://coolak.github.io/anthropic-claude-billing-incident/reconciliation-matrix.html