Before You Trust "Credit balance is too low": Three Balances That Don't Share a Wallet

One morning the output of last night's summary script was empty. The log ended with a single English line:

Your credit balance is too low to access the Anthropic API.

I was on a Max plan, and the plan was supposed to include monthly API credits. My stomach dropped a little. It didn't add up.

What I'd like to say first: that message often doesn't mean you're out of money. It means the wallet that pays for the thing you just called is empty. Below is the order I use to tell the wallets apart, and a small wrapper I keep in unattended scripts. I'm an indie developer running small scheduled jobs, so this is written from that seat.

There is more than one wallet

Reading Anthropic's docs and Help Center again, API payment turns out to be three mechanisms layered together.

Included credits are spent first, purchased credits second. Auto-reload looks at the purchased balance only, so it can fire even while included credits remain.

Check what you called before you check the number

My first question is about the call that failed, not the balance. Included credits cover the Claude API, Managed Agents, the Agent SDK and the Console playground. They do not cover Claude Code or extra usage in the Claude apps.

So if an organization holds only included credits and you run Claude Code, you'll see this:

Credit balance too low · Add funds: https://platform.claude.com/settings/billing

If your API balance looks healthy and you still see it, the cause may be "wrong kind of call," not an empty balance. Before buying anything, I go in this order:

1. Open the Console Billing page: is Credit balance at zero, or Promotional credits?
2. Was the failing call the API / Agent SDK, or Claude Code?
3. On the Cost page, is this month's spend close to the monthly cap?

The third is easy to miss. I wrote up how to tell the cap errors apart in a separate piece on telling a self-set limit, a tier's monthly cap and a rate limit apart when a 400 comes back. The symptoms look alike, but the fixes don't.

What I changed after getting burned

I used to think a failed overnight job could simply be noticed the next morning. But included credits vanish at the end of a billing cycle, so they can run out at an hour nobody is watching.

Now I don't rely on the console to tell me. The code that makes the call reports "the wallet is empty" in its own words. This wrapper treats the balance error separately and exits with a distinct code.

import sys
import anthropic
 
client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment
 
LOW_BALANCE_MARK = "credit balance is too low"
 
def ask(prompt: str) -> str:
    try:
        msg = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=512,
            messages=[{"role": "user", "content": prompt}],
        )
        return msg.content[0].text
    except anthropic.APIStatusError as e:
        # Retrying never fixes an empty balance, so stop with exit code 3
        if LOW_BALANCE_MARK in str(e).lower():
            print("Low balance: check Credit balance and Promotional credits on Billing", file=sys.stderr)
            sys.exit(3)
        raise  # anything else goes to your normal error handling
 
if __name__ == "__main__":
    print(ask("Summarize today's notes in three lines."))

It solves one thing: a job that keeps retrying all night against an empty balance. Waiting won't fix this error, so it's excluded from retries and stopped with a fixed marker. If your cron or scheduler notifies only on exit code 3, it won't get mixed in with other failures.

Decide how you'll refill before it runs dry

Two decisions, made in advance, are much calmer than a panicked purchase.

• Auto-reload or not. You set a trigger ("When credit balance reaches") and a target ("Bring credit balance back up to"). If you enable it while already below the trigger, it charges immediately.
• Who can buy. Buying credits and changing the payment method needs the Admin or Billing role. Even solo, check your role after recreating an organization.

To keep one project from eating everything, give it its own workspace and set a spend limit on that workspace, since keys and workspaces in one organization draw from the same balance. For the key side, see how I turn API key expiry into a scheduled event. If the problem is the payment method itself, this billing and payment error roundup is the place to start.

My rule

Put the "about to run dry" signal in code, not on a screen. A screen tells you nothing unless you go look; an exit code has already arrived by morning.

If you run anything unattended, pick one script and make it stop on this error with its own exit code. That's where I started, and I'd rather keep it that way.