Claude CodeUnverified

Fix Claude Code API Error 400: "out of extra usage" Billing Routing Triggered by "HERMES.md" in Git Commit Messages

When a git repository's recent commit history contains the case-sensitive string "HERMES.md", Claude Code routes API requests to "extra usage" billing instead of the included Max plan quota. This silently burns through extra usage credits ($200+ in reported cases) while plan capacity remains largely untouched. The error message ('out of extra usage') gives no indication that content-based routing is the cause, making it extremely difficult to diagnose. Anthropic staff (bcherny) confirmed: 'This was an overactive anti-abuse system. Fixed.' The fix was applied server-side. Workarounds include rewriting commit messages to use lowercase 'hermes.md' or using orphan branches to isolate project history.

Symptoms

Claude Code returns 'API Error: 400 - You're out of extra usage' despite having remaining plan quota
Plan dashboard shows 85%+ remaining weekly capacity while all requests fail with 'out of extra usage'
API requests are silently routed to extra usage billing instead of plan quota for specific projects
Multiple projects become completely unusable after extra usage credits are depleted, with no indication of the real cause
The error message gives no hint that git commit message content is the trigger — looks like a generic quota error

Error signatures

API Error: 400

You're out of extra usage

out of extra usage

Possible causes

Overactive server-side anti-abuse system incorrectly routing requests based on git commit message content in the system prompt
Case-sensitive string match on 'HERMES.md' in recent git commit messages triggers different billing routing logic
The trigger is specifically the string 'HERMES.md' in commit messages — not the presence of a file with that name on disk, and only the exact case-sensitive match triggers it (lowercase 'hermes.md', 'HERMES.txt', 'HERMES' without extension do NOT trigger)
The regex or pattern-matching logic was overly broad, catching legitimate users whose projects reference HERMES.md (a common AI agent instruction file format) in their git history
Claude Code includes recent git commit messages in its system prompt context sent to the API — the server-side anti-abuse system scans this context and mistakenly flags 'HERMES.md' as an indicator of unauthorized agent usage

Solutions

Diagnostic Method: Binary Search to Isolate Content-Based Routing Triggers

risk: lowgithubpending_review

The reporter used a systematic binary search approach to identify 'HERMES.md' as the exact trigger string. This method helps diagnose similar content-based routing anomalies: clone the repo, test orphan branches, then isolate individual commit message substrings until the triggering string is identified. Use this when you encounter 'out of extra usage' errors that don't match known triggers.

Clone the affected repository to a temporary location: git clone <repo> /tmp/test-repo
Test with an orphan branch to confirm git history (not file content on disk) is the cause
Extract recent commit messages and test each one individually in a clean git repo
Once a candidate trigger is found, test variations (case, extension, partial string) to confirm specificity
Document the exact trigger string and share findings with Anthropic support if it's a new trigger

Commands

git clone <repo> /tmp/test-repo 2>/dev/null && cd /tmp/test-repo

git checkout --orphan test-orphan 2>/dev/null && claude -p 'test' 2>&1 | grep -q 'extra usage' || echo 'PASS: orphan branch works — confirms history-based trigger'

rm -rf /tmp/test-each-* 2>/dev/null; git log --format='%s' -20 | while read msg; do DIR="/tmp/test-each-$$-$(echo $msg | md5sum | cut -c1-8)"; mkdir -p "$DIR" && cd "$DIR" && git init 2>/dev/null && echo t > t.txt && git add . 2>/dev/null && git commit -m "$msg" 2>/dev/null && claude -p 't' 2>&1 | grep -q 'extra usage' && echo "TRIGGER FOUND: $msg"; done; rm -rf /tmp/test-each-* 2>/dev/null

Risks

Binary search on large git histories can be time-consuming — each iteration makes an API call
Rate limiting or actual quota exhaustion can produce false positives — verify you have remaining quota before starting
The diagnostic method itself consumes API credits during testing — budget ~20 calls for a typical search
Some commit messages may contain shell-special characters; the while-read loop handles most but edge cases with backticks or $() may need manual escaping

Verification

Confirm orphan branch test passes: 'PASS: orphan branch works — confirms history-based trigger' should appear in output
A successful trigger identification outputs: 'TRIGGER FOUND: <exact commit message or substring>'
No false positives: the diagnostic should only flag messages that consistently reproduce the 'out of extra usage' error
After identifying a trigger, validate by testing in isolation: create a fresh repo with ONLY that commit message → EXPECTED: reliably reproduces the billing routing issue

✓ 0 verified✕ 0 failed

Immediate Workaround: Remove 'HERMES.md' from Git Commit Messages

risk: lowgithubpending_review

Before the server-side fix was deployed, users could work around the issue by ensuring no git commit messages in the project's history contain the case-sensitive string 'HERMES.md'. Options include: rewriting commit messages to use lowercase 'hermes.md', using an orphan branch to isolate work, or amending affected commits. The trigger is purely case-sensitive string matching in commit messages — files named HERMES.md on disk do NOT cause the issue.

Identify commits containing 'HERMES.md': git log --all --grep='HERMES.md' --oneline
Option A (safest): Create an orphan branch to work without any commit history containing the trigger: git checkout --orphan clean-branch
Option B (single commit): Amend the most recent commit if it is the only affected one: git commit --amend -m 'hermes.md: new message'
Option C (multi-commit): Use git filter-branch to rewrite all affected commit messages: git filter-branch -f --msg-filter 'sed "s/HERMES.md/hermes.md/g"' HEAD~N..HEAD

Commands

git log --all --grep='HERMES.md' --oneline 2>/dev/null

git checkout --orphan clean-branch 2>/dev/null && git add . && git commit -m 'hermes.md: initial commit'

git commit --amend -m 'hermes.md: new message'

git filter-branch -f --msg-filter 'sed "s/HERMES.md/hermes.md/g"' -- --all 2>/dev/null

Risks

Rewriting git history with filter-branch or rebase can break references in other branches, forks, or CI pipelines
Orphan branches lose all previous history, making it harder to trace changes
If other developers have based work on the original commits, force-pushing rewritten history can cause conflicts — coordinate with your team before force-pushing
git filter-branch rewrites ALL branches; use --all carefully or target specific refs

Verification

After rewriting history, run: claude -p 'say hello' 2>&1 → EXPECTED OUTPUT: 'Hello!' (greeting without any error)
Verify lowercase trigger immunity: create a test commit with lowercase → git commit -m 'add hermes.md' && claude -p 'test' 2>&1 → EXPECTED: normal Claude response without 'out of extra usage' error
Run 'git log --all --grep=HERMES.md --oneline 2>/dev/null' → EXPECTED OUTPUT: (empty — no commits found with the triggering string)
Check /cost → EXPECTED: usage counted against plan quota, not extra usage

✓ 0 verified✕ 0 failed

Server-Side Fix (Applied by Anthropic) — Primary Resolution

risk: lowofficialpending_review

Anthropic staff (bcherny) confirmed on the GitHub issue: 'This was an overactive anti-abuse system. Fixed.' The fix was deployed server-side and does not require a Claude Code client update. All users should verify the fix resolves their issue by running the reproduction test below. If the issue persists after updating Claude Code to the latest version, the underlying cause may be different (e.g., actual quota exhaustion or other anti-abuse triggers).

Update Claude Code to the latest version: run 'claude --version' and compare with latest release from GitHub
Run the reproduction test case (see verification_steps) to confirm the fix is active for your account
If the test passes, continue normal usage — the server-side routing fix is active
If the test still fails, rule out legitimate quota exhaustion by checking /cost, then contact Anthropic support with the reproduction test output

Commands

claude --version

mkdir -p /tmp/test-fix && cd /tmp/test-fix && git init 2>/dev/null && echo test > test.txt && git add . && git commit -m 'add HERMES.md' && claude -p 'say hello' --model 'claude-opus-4-6[1m]'

Risks

If still experiencing the issue after the server-side fix, the root cause may be different from the HERMES.md trigger — check for other potential anti-abuse triggers in your git history (e.g., 'CLAUDE.md', 'AGENTS.md', or other agent config filenames)
The reproduction test consumes one API call — verify you have remaining quota before testing

Verification

Run reproduction test: mkdir -p /tmp/test-fix && cd /tmp/test-fix && git init 2>/dev/null && echo test > test.txt && git add . && git commit -m 'add HERMES.md' && claude -p 'say hello' --model 'claude-opus-4-6[1m]' 2>&1 → EXPECTED OUTPUT: 'Hello!' (plain greeting, no error message)
Run: cd /tmp && rm -rf test-fix → cleanup test directory
Check '/cost' command output → EXPECTED: usage subtracted from plan quota (e.g., 'Max 20x plan: 13% used this week'), NOT from extra usage credits
Confirm the issue does NOT reproduce: the string 'out of extra usage' or 'API Error: 400' should NOT appear anywhere in the output

✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "6c5196b3-ddec-4c48-9133-09f48aa99c86",
  "slug": "fix-claude-code-api-error-400-out-of-extra-usage-billing-routing-triggered-by-hermes-md-in-git-commit-messages-yxc9q2",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-claude-code-api-error-400-out-of-extra-usage-billing-routing-triggered-by-hermes-md-in-git-commit-messages-yxc9q2"
}