One morning I typed claude into the terminal as usual, and before the prompt even appeared I got a line of red text: "Credit balance is too low to access the API. Please go to Plans & Billing to upgrade or purchase credits." It had worked fine the day before. As an indie developer who has built apps since 2014, I run the auto-publishing pipelines for my four Dolice Labs sites overnight, and I once woke up to find every job had died on exactly this one line.
This error reads like "you're out of money," but the real cause is almost always a mismatch in which auth path is being billed. Slow down, isolate it, and you can recover in a couple of minutes. Let's walk through it.
First: which path is billing you right now?
Claude Code has two billing paths, and mixing them up is by far the most common cause here.
One is subscription login auth (Pro / Max). After you run /login and complete the browser sign-in, Claude Code runs inside your subscription allowance. That allowance has nothing to do with your API credit balance.
The other is API key (ANTHROPIC_API_KEY) usage-based billing. If you put a key issued in the Anthropic Console into your environment, Claude Code consumes the credit balance tied to that key. When the balance hits zero, you get the error above.
Here is the trap: if ANTHROPIC_API_KEY is set in your environment, it takes priority even when you are logged in with a subscription. An old key lingering in .zshrc, or a CI variable that also happens to be active locally, means you think you're on the subscription while Claude Code is actually checking the API balance — and stopping at zero. That is the real story behind "I'm subscribed but it says I'm out of credit."
Check which path you're on first:
# Is an API key set in your environment?
echo "$ANTHROPIC_API_KEY"
# You can also check inside Claude Code itself:
# run /status in an interactive session to see the active auth methodIf echo prints a string, you're being billed through that API key. If it's empty, you're running on subscription login auth.
Fix 1: Want the subscription? Remove the API key
If you have Pro / Max and want Claude Code to run inside that allowance, the fastest fix is to remove the API key from your environment.
# Unset temporarily to test (this shell only)
unset ANTHROPIC_API_KEY
claude
# To remove it permanently, delete the line from your shell config
grep -rn "ANTHROPIC_API_KEY" ~/.zshrc ~/.bashrc ~/.profile 2>/dev/nullAfter deleting the line, open a fresh terminal, start claude, and authenticate your subscription account with /login. It will stop reaching for the API credit balance.
One caveat worth stating plainly: unset only affects the current shell session. Open a new tab and .zshrc reloads, bringing the key back. If you "just fixed it and it came back," that's almost always why. The fix isn't done until the line is gone from the config file itself.
Fix 2: Want usage-based API billing? Top up the balance
Sometimes you genuinely want to run on an API key — automation pipelines, CI, that kind of thing. In my own setup I split this deliberately: interactive development on the subscription, unattended auto-publishing on an API key. In that case, add credits.
Log into the Anthropic Console (console.anthropic.com) and buy credits under Plans & Billing → Credits. You can't purchase without a payment method on file, so register a card first. Once the top-up lands, the same API key starts working again.
The single most useful thing for unattended work is Auto-reload: when the balance drops below a threshold, it automatically tops up by a set amount. With it on, you stop getting "pipeline dead at 3am because the balance hit zero." Years of running AdMob-monetized apps trained me to prefer "never get paged at night" setups, so ever since the overnight wipeout I described above, I keep this enabled on every workspace I use for automation.
Fix 3: On an org account? Suspect spend limits and workspaces
If you use a team or organization Console account, the cause can be a per-workspace spend limit. The org's overall credits may be fine, but if a specific workspace has hit its assigned monthly cap, only that key reports an insufficient balance.
Check and adjust the limit under the Console's Settings → Limits (or the relevant workspace settings). If you're not an admin, you'll need to ask whoever owns the limit to raise it. I've noticed a lot of people hit this exactly once, right when they move from solo work to corporate engagements.
Keeping it from happening again
Once you understand the mechanism, isolating this error on a future occurrence takes seconds. A few habits I stick to:
Pin each auth path to a purpose. Subscription login for interactive development, a dedicated API key for unattended automation. Decide that up front and you never wonder which balance to check. Leaving an automation key sitting in your local .zshrc mixes the paths, so I export automation keys only inside the job script itself.
And for API-key work, turn on Auto-reload. Trying to watch the balance by hand means it goes to zero right when you've stopped paying attention. Let the mechanism keep you from stalling — that, in the end, is the quietest way to run.
Before you reflexively buy credits because the message says "purchase credits," run echo "$ANTHROPIC_API_KEY" once and confirm the path. The case where the subscription would have been plenty, but it was checking usage-based billing instead, is remarkably common.
I hope this saves you the first few minutes if you hit the same wall.