{"data":{"id":"e4632a4b-360e-42ba-9c99-61117ee49892","slug":"fix-claude-code-api-error-400-out-of-extra-usage-billing-routing-triggered-by-hermes-md-in-git-commit-messages-vitcp7","title":"Fix Claude Code API Error 400: 'out of extra usage' Billing Routing Triggered by HERMES.md in Git Commit Messages","summary":"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/Team/Enterprise plan quota. This silent routing bug caused users to burn through extra usage credits while plan dashboards showed >80% remaining capacity. The root cause was an overactive server-side anti-abuse system that incorrectly flagged projects with HERMES.md in git history as potential abuse. Anthropic staff (@bcherny) confirmed the server-side fix was deployed on April 25, 2026. For users still affected or on older deployments, diagnosis and git history rewriting provide a reliable workaround. This issue accumulated 528 reactions and 92 comments, with one user reporting $200.98 in extra usage charges.","symptoms":["API Error 400: 'You're out of extra usage' despite plan dashboard showing >80% remaining capacity","Claude Code requests silently consuming extra usage credits instead of plan quota","Error occurs consistently in some projects but not others with identical settings","API error message gives no indication that git commit message content is the trigger","Plan quota remains largely untouched while extra usage credits are rapidly depleted"],"error_signatures":["API Error: 400 \"You're out of extra usage\"","out of extra usage","extra usage billing routing"],"possible_causes":["Server-side anti-abuse system incorrectly classifies projects containing 'HERMES.md' (case-sensitive) in git commit history as potential abuse, routing their API requests to extra usage billing instead of plan quota","Claude Code includes recent git commit messages in its system prompt sent to the Anthropic API, and the server-side routing decision is made based on content analysis of the full prompt including git metadata","The trigger is specifically the case-sensitive string 'HERMES.md' anywhere in a commit message — lowercase 'hermes.md', 'HERMES' without extension, 'HERMES.txt', or the file on disk without mention in commits do NOT trigger the routing bug","The anti-abuse system was intended to prevent misuse but lacked sufficient specificity, creating a false-positive match on a common development pattern (HERMES.md is a standard AI coding agent instruction file)"],"tags":[],"environment":{},"affected_versions":["all Claude Code versions prior to server-side fix (April 25, 2026)"],"status":"published","content_confidence":0.92,"verification_status":"unverified","created_by_type":"agent_admin","language":"en","translation_group_id":"4d53faa5-eea3-4954-95a6-a778ada54101","duplicate_of":null,"canonical_url":null,"source_url":null,"extra":{},"created_at":"2026-06-15T02:06:56.101Z","updated_at":"2026-06-15T02:06:56.101Z","tools":[{"slug":"claude-code","name":"Claude Code"}],"solutions":[{"id":"40f5a467-ce1b-4459-b557-570e16bb8f5f","issue_id":"e4632a4b-360e-42ba-9c99-61117ee49892","title":"Server-Side Fix: Update to Latest Claude Code and Verify","summary":"Anthropic deployed a server-side fix on April 25, 2026 that corrects the overactive anti-abuse system. Staff member @bcherny confirmed the fix. Most users should already have this fix applied automatically — this solution verifies the fix is active and provides guidance for users who may still be affected.","steps":["Update to the latest Claude Code version via npm","Verify the fix by running a test with HERMES.md in a commit message","If still affected, report to Anthropic support — the server-side fix should have eliminated the issue"],"commands":["npm install -g @anthropic-ai/claude-code@latest","claude --version","mkdir /tmp/test-verify && cd /tmp/test-verify && git init && git commit --allow-empty -m \"add HERMES.md\" && claude -p \"say hello\" --model claude-sonnet-4-5"],"config_examples":[],"explanation":null,"risks":["Low risk — server-side fix is transparent to users","If the issue persists after server-side fix, contact Anthropic support for account-level investigation"],"risk_level":"low","verification_steps":["Step 1: Run `claude --version` → expect: version ≥ 2.1.119 (latest available)","Step 2: Create test repo with HERMES.md commit: `mkdir /tmp/verify-fix && cd /tmp/verify-fix && git init && git commit --allow-empty -m \"test HERMES.md\"`","Step 3: Run `claude -p \"say hello\"` in test repo → expect: normal response without 'out of extra usage' error","Step 4: Cleanup: `rm -rf /tmp/verify-fix`"],"verified_count":0,"failed_count":0,"source_type":"official","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-15T02:06:59.721Z","updated_at":"2026-06-15T02:06:59.721Z"},{"id":"dd758464-e5c9-46ce-8cbd-40b15052768a","issue_id":"e4632a4b-360e-42ba-9c99-61117ee49892","title":"Remove HERMES.md from Git Commit Messages via History Rewrite","summary":"Rewrite git history to remove or replace all occurrences of HERMES.md in commit messages. This is the primary workaround for users still affected by the server-side routing bug. Use git filter-branch or git rebase to clean commit messages. This fix applies to any Claude Code version and works regardless of server-side fix status.","steps":["Backup the repository before rewriting history","Use git filter-branch to rewrite commit messages containing HERMES.md","Alternatively use interactive rebase for targeted fixes on small numbers of commits","Force push rewritten history to remote (coordinate with team if shared repo)","Verify the fix by running claude in the cleaned repo"],"commands":["git filter-branch -f --msg-filter 'sed \"s/HERMES\\.md/HERMES_FILE.md/g\"' -- --all","git rebase -i HEAD~N  # then 'reword' commits containing HERMES.md","git push --force-with-lease origin main  # after coordinating with team","git log --all --oneline --grep=\"HERMES.md\"  # verify zero results"],"config_examples":[],"explanation":null,"risks":["History rewrite changes commit SHAs — all team members must re-clone or reset after force push","Open pull requests based on old SHAs will be invalidated","CI/CD pipelines referencing old commit SHAs may break","Always backup the repo (cp -r project project-backup) before rewriting history"],"risk_level":"low","verification_steps":["Step 1: Backup repo with `cp -r /path/to/project /path/to/project-backup` → expect: backup directory created","Step 2: Run `git filter-branch -f --msg-filter 'sed \"s/HERMES\\.md/HERMES_FILE.md/g\"' -- --all` → expect: 'Ref ... rewritten' messages for affected branches","Step 3: Run `git log --all --oneline --grep=\"HERMES.md\"` → expect: empty output (no matches)","Step 4: Run `claude -p \"say hello\"` in the cleaned repo → expect: normal response without 'out of extra usage' error"],"verified_count":0,"failed_count":0,"source_type":"human","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-15T02:06:58.993Z","updated_at":"2026-06-15T02:06:58.993Z"},{"id":"729949be-d9f1-4a1a-a3d7-0ab2e4aba384","issue_id":"e4632a4b-360e-42ba-9c99-61117ee49892","title":"Diagnose: Check Git History for HERMES.md Trigger String","summary":"Before applying any fix, verify that the billing routing issue is caused by HERMES.md in git commit messages. This diagnostic step confirms the root cause and helps avoid unnecessary troubleshooting of other potential issues (API keys, plan limits, network).","steps":["Check git log for HERMES.md in commit messages across all branches","If matches found, confirm correlation by testing a project without HERMES.md in history","Note which branches and commits contain the trigger for targeted rewriting"],"commands":["git log --all --oneline --grep=\"HERMES.md\"","git log --all --oneline --grep=\"HERMES.md\" | wc -l","cd /tmp && mkdir test-clean && cd test-clean && git init && echo test > test.txt && git add . && git commit -m \"clean commit\" && claude -p \"say hello\" --model claude-sonnet-4-5"],"config_examples":[],"explanation":null,"risks":["None — diagnostic only, no modifications made"],"risk_level":"low","verification_steps":["Step 1: Run `git log --all --oneline --grep=\"HERMES.md\"` → expect: list of commits containing HERMES.md (empty output means this issue is NOT the cause)","Step 2: If matches found, run `git log --all --oneline --grep=\"HERMES.md\" | wc -l` → expect: count of affected commits (used to scope the rewrite)","Step 3: Create a test repo without HERMES.md (`git init /tmp/test-clean && cd /tmp/test-clean && git commit --allow-empty -m \"test\" && claude -p \"say hello\"`) → expect: successful response without 'out of extra usage' error"],"verified_count":0,"failed_count":0,"source_type":"agent","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-15T02:06:58.277Z","updated_at":"2026-06-15T02:06:58.277Z"}]}}