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

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] 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)

• #51550 / #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)
• #14363 (mine, closed not-planned) — requested a direct billing/settings link on the spend-limit message
• #65019 / #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 <time>" 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_