Claude Code Exceeded USD Budget on Max? Check Billing Mode

If a headless Claude Code run on a Pro or Max subscription stops with Exceeded USD budget, do not assume that Anthropic charged your API account. The --max-budget-usd guard compares Claude Code's estimated token cost with the limit you supplied. That estimate can stop a subscription-backed run even when the subscription absorbs the usage.

Verify the active authentication path before changing the command. If Claude Code is using an API key, Amazon Bedrock, Google Vertex AI, or Microsoft Foundry, keep the dollar cap. If the run is genuinely using subscription OAuth, retry one harmless bounded prompt without --max-budget-usd and keep independent limits on turns, wall-clock time, tools, and output.

Check Authentication Before Removing the Cap

Start with Claude Code's own status command:

claude auth status

In an interactive session, /status also shows the active account and authentication method. Then check whether the shell is overriding subscription authentication. Print variable names, not secret values:

env | grep -E \
  '^(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN|CLAUDE_CODE_USE_BEDROCK|CLAUDE_CODE_USE_VERTEX|CLAUDE_CODE_USE_FOUNDRY)=' \
  | sed 's/=.*/=<set>/'

An ANTHROPIC_API_KEY can take precedence over a Pro or Max login and produce API charges. Provider flags can route the run to a cloud account with separate billing. A subscription visible in the Claude app is therefore not enough to prove that a particular terminal process uses subscription capacity.

Use this decision table before editing an automation:

Do not unset credentials blindly. Other jobs in the same shell may depend on them. Prefer a clean subprocess environment or a dedicated automation account after you identify the intended billing mode.

Why a Subscription Run Can Hit a Dollar Limit

Anthropic documents the agent budget as a client-side cost estimate. Claude Code can calculate an API-price equivalent from token usage even when the user is authenticated through a fixed-price subscription. --max-budget-usd 1 therefore means "stop when the estimate reaches one dollar," not "stop only after Anthropic invoices one dollar."

Claude Code issue 85400 reports the exact mismatch in headless mode: a Max subscriber ran claude -p with --max-budget-usd 1.00, the command stopped with Exceeded USD budget (1), and the reported total cost remained $0.0000. That is an open user report, not a confirmed root-cause statement or a released fix.

An independent investigation reached the same practical conclusion: the guard follows the accumulated cost estimate returned during a run and can activate under fixed billing. The limit can still be valuable for API-backed work. The mistake is treating one flag as both an API spend cap and a subscription usage cap.

Replace One Guard With Several Bounded Guards

For a verified subscription-backed job, remove only the mismatched dollar guard. Keep limits that constrain the work directly.

This Linux example allows at most four agentic turns and two minutes:

timeout --signal=TERM 120s \
  claude -p \
  --max-turns 4 \
  --permission-mode plan \
  "Read CLAUDE.md and return its first Markdown heading. Do not edit files."

On macOS, install GNU coreutils and use gtimeout, or use the timeout mechanism in your process supervisor, CI runner, container, or job queue. Test the wrapper's timeout behavior separately; do not assume every platform ships the same command.

The useful safeguards cover different failure modes:

• --max-turns limits model and tool round trips.

• A wall-clock timeout limits hangs, slow streams, and runaway children.

• --permission-mode plan or a narrow allowed-tools list prevents writes during a diagnostic run.

• A small prompt and explicit output contract limit the requested work.

• A postcondition verifies the file, JSON, exit event, or other deliverable the job actually needs.

For a real automation, choose limits from its expected workload instead of copying the example values. Four turns may be enough for a read-only check and far too small for a repository migration.

Test the Change Without Risking a Production Job

Use a harmless prompt first. Capture stdout, stderr, exit status, duration, and Claude Code version for two otherwise identical runs:

1. Run with the existing --max-budget-usd value.

2. Run without that flag but with --max-turns, a wall timeout, and read-only permissions.

3. Confirm both runs use the same subscription authentication path.

4. Confirm the bounded run produces the expected answer and terminates inside the limit.

5. Restore the dollar cap immediately if the process resolves to API or provider billing.

Do not use a long coding task as the probe. A one-line read-only answer separates the budget behavior from repository writes, tool approvals, and output validation.

Also remember that exit 0 does not prove the requested side effect happened. If the automation expects a file, inspect the exact path and content before the next step. The same principle applies to generated images, test reports, pull requests, and deployment artifacts.

Keep the Dollar Cap for API-Billed Work

--max-budget-usd is appropriate when the estimated cost tracks spend you may actually incur. Keep it when an API key or cloud provider is active, and combine it with operational limits rather than relying on it alone.

A practical API-backed command can use both controls:

timeout --signal=TERM 600s \
  claude -p \
  --max-budget-usd 5 \
  --max-turns 20 \
  "Analyze the requested repository scope and return the required JSON."

The dollar cap limits estimated spend. The turn cap and timeout limit execution shape. Your output validator still decides whether the job succeeded.

For a broader usage investigation, see How to Diagnose Claude Code Usage Limit Spikes. For a reusable acceptance gate, see How to Verify AI Coding Agent Tests Actually Pass.

Audit a Headless Command With Aident Loadout

Start with this exact setup phrase:

Follow https://aident.ai/SETUP.md

Then ask:

Find the current Claude Code documentation and GitHub evidence for --max-budget-usd under subscription authentication. Compare the flag with --max-turns and wall-clock timeouts. Return a billing-mode decision table and a bounded read-only test command. Do not execute Claude Code, modify credentials, publish content, or remove a dollar cap unless the active billing mode is proven.

Aident Loadout can discover current search and repository Actions, inspect their schemas, and preflight any priced research before execution. The acceptance condition is a source-backed decision table and a non-destructive test plan, not an automatic credential change.

Set up Aident Loadout and audit the budget guard.

Sources

• Claude Code CLI reference

• Use Claude Code with your Pro or Max plan

• Models, usage, and limits in Claude Code

• Claude Code issue 85400: Max plan run exceeds a USD budget

• When the Docs Fall Short: Investigating Claude Code's Budget Cap

Refresh this guide when Anthropic closes issue 85400 with a released fix, changes subscription authentication precedence, or changes the semantics of --max-budget-usd, --max-turns, or headless mode.