Fix "Credit balance is too low" in Claude Code

If you pay for a Claude plan and Claude Code says "Credit balance is too low", your requests are not going to your plan. They are going to an Anthropic Console account whose prepaid credits have run out. On a subscription, the cause Anthropic documents is an approved ANTHROPIC_API_KEY being used instead of your login. Run /status, check the API key row, and if a key is in use, unset it, remove it from your shell profile and relaunch claude.

What the message means

Anthropic's error reference gives two causes for this exact message: "Your Console organization has run out of prepaid credits, or Claude Code is sending your requests with a Console API key when you meant to use your subscription."

A plan (Pro, Max, Ultra, Team or Enterprise) and a Console account are two separate ways to pay for Claude Code. A plan has usage limits; when you reach one you see a message such as "You've hit your session limit". A Console account pays per token from a prepaid credit balance, and Anthropic describes API key billing as pay-as-you-go with "No hard stop" (models, usage and limits in Claude Code). A credit balance only exists on the Console side. So if you meant to use a plan, the real question is why Claude Code is talking to the Console.

Cause 1: an API key is winning over your plan

Anthropic's Help Center puts it plainly: "If you have an ANTHROPIC_API_KEY environment variable set on your system, Claude Code will use this API key for authentication instead of your Claude subscription (Pro, Max, Ultra, Team, or Enterprise plans), resulting in API usage charges rather than using your subscription's included usage" (use Claude Code with your plan).

In interactive sessions Claude Code asks once whether to use the key and remembers your answer; with -p, a key that is present is always used. So a yes from months ago can still be in force. The full order in which Claude Code picks a credential is in why Claude Code bills your API key instead of your plan.

The key can come from somewhere you did not expect. Anthropic's errors page notes that "Tools like direnv, dotenv shell plugins, and IDE terminals can load a stale key from a .env file in your project without you setting it explicitly." One user reported exactly that, a project .env key used instead of a Max plan (GitHub issue #58083); treat that as a user report.

How to check

Run /status. It shows version, model, account and connectivity, and when a login and an API key are both configured, it marks the credential that is not in use (authentication docs). If the API key row is not marked as unused, the key is what Claude Code is sending. To see the variable from the shell you launch Claude Code in:

env | grep ANTHROPIC

How to fix

Anthropic's steps for this error are to unset the key in the current shell, remove it from your shell profile, then relaunch claude, and to run /login if you have not signed in with your subscription yet. The first part is one command:

unset ANTHROPIC_API_KEY

Then delete the line that exports it from your shell profile (for example ~/.zshrc) and from any .env file a tool loads into your terminal, so it does not come back in the next window. Start Claude Code again and run /status to confirm it is on your subscription login. If you approved the key earlier, also switch off the "Use custom API key" toggle in /config, which only appears while the variable is set.

Running /login alone does not fix this while an approved key is set. Anthropic's docs say such a key "takes precedence over your login, so /login doesn't replace it." Users have reported the same thing (GitHub issue #108904).

Cause 2: your Console organization is out of credits

If you deliberately use a Console account, the message means what it says. A Console sign-in is a separate account type from a Claude subscription in Claude Code's login (authentication docs), and it draws on that organization's prepaid balance. When the balance is empty, requests fail.

Anthropic's fixes on the error reference:

• Add credits at platform.claude.com/settings/billing, and consider enabling auto-reload there so the balance refills before it hits zero.
• Set per-workspace spend caps in the Console so one project cannot drain the whole organization's balance.

If you meant to use your plan instead, sign in again and pick the subscription. From a shell, claude auth login --claudeai is the subscription option and the default; --console is the API billing one (from claude auth help login on Claude Code 2.1.322).

Monthly API credits can run out too

Max, Ultra and Team include monthly Claude Platform credits, which land in the one Console organization you link. If you run the Agent SDK or claude -p with a key from that organization, and the monthly credits are used up with no purchased credits behind them, "API requests stop until your next monthly credits arrive" (monthly API credits). These credits never pay for interactive Claude Code, and Pro "does not include API usage through the Claude Console" at all (Pro plan). The split is explained in monthly API credits vs usage credits.

Is it maybe just a limit?

If what you see is "You've hit your session limit", "You've hit your weekly limit" or a message about a spend limit, that is your plan or your usage credits, not a Console balance. Use the session limit guide instead.

"API Error: Request rejected (429)" is another message people mix up. Per Anthropic it means the rate limit configured for an API key, Amazon Bedrock project or Google Cloud project, not a subscription limit, and the first suggested step is /status again (errors).

Stopping it happening again

• Keep ANTHROPIC_API_KEY out of your shell profile if you also use a subscription. Anthropic's advice is to keep it unset and, if you need a key occasionally, "set it temporarily only when needed" (managing API key environment variables).
• After you sign in, Claude Code shows a notification if both a login and a key are active. Read it before dismissing it.
• Run /status now and then; the same article recommends checking it "periodically".
• Remember the variable also applies to the surfaces that wrap the CLI, including the VS Code extension, the Agent SDK and GitHub Actions. Claude Desktop and cloud sessions use OAuth instead.

What a menu bar tracker can and cannot do here

Headroom, a free Mac menu bar app, tracks plan usage for Claude Code accounts signed in on your Mac. It does not track API key or Console billing, so it will not tell you a Console balance is low. What it can help with is the opposite case: a row showing "Ready" with low percentages tells you your plan has room, which points to a routing problem rather than a plan limit as the cause of this error. It never sends a prompt, and it is independent, not made or endorsed by Anthropic. Get it at headroom.everydaymactools.com.