hermes - 💡(How to fix) Fix [Bug]: OAuth Pro/Max credential returns "out of extra usage" 400 immediately after fresh login, despite empty/unused account quota [1 pull requests]

Bug Description

Hermes version: v0.14.0 (2026.5.16) Config version: 24 OpenAI SDK: 2.24.0 Python: 3.11.15 (Hermes venv) OS: Ubuntu, Linux 6.8.0-110-generic

Summary

Every chat completion request from Hermes against a freshly authorized Claude Pro/Max OAuth credential immediately fails with HTTP 400 "You're out of extra usage. Add more at claude.ai/settings/usage and keep going." — even though the Anthropic account's usage page shows the plan as essentially unused for the current cycle. This makes the Max subscription effectively unusable through Hermes.

Steps to reproduce

1. Start with a clean Claude Pro/Max account (no recent Claude Code / Hermes activity).
2. Remove any existing anthropic credentials: hermes auth remove anthropic <label>
3. Add a fresh OAuth credential: hermes auth add anthropic --type oauth --no-browser --manual-paste
4. Complete the Pro/Max authorization flow at https://claude.ai/oauth/authorize?... (standard Claude Code OAuth client 9d1c250a-..., scopes org:create_api_key user:profile user:inference).
5. Paste the returned code; credential is stored in ~/.hermes/auth.json (auth_type: oauth, source: manual:hermes_pkce).
6. Restart hermes-gateway (so it picks up the new credential).
7. Send any message — e.g. via Mattermost platform, or hermes -z "ping".

Expected

Request succeeds (or, at worst, fails with a token/scope error that points to a real configuration problem).

Actual

Request reaches Anthropic and returns: HTTP 400 { "type": "error", "error": { "type": "invalid_request_error", "message": "You're out of extra usage. Add more at claude.ai/settings/usage and keep going." }, "request_id": "req_011CbPw84JVcAuAgPxZCJa1U" }

claude.ai/settings/usage for the same account shows no/minimal consumption for the current cycle.

Auth state at time of failure (hermes auth list)

anthropic (1 credentials): #1 anthropic-oauth-2 oauth hermes_pkce ← No ANTHROPIC_API_KEY set in environment, .env, systemd unit, or shell.

Gateway log excerpt

2026-05-25 20:40:21 INFO gateway.run: inbound message: platform=mattermost ... msg='ping' 2026-05-25 20:40:23 WARNING agent.conversation_loop: API call failed (attempt 1/3) error_type=BadRequestError provider=anthropic base_url=https://api.anthropic.com model=claude-sonnet-4-6 summary=HTTP 400: You're out of extra usage. Add more at claude.ai/settings/usage and keep going. 2026-05-25 20:40:23 ERROR agent.conversation_loop: Non-retryable client error: Error code: 400 - {'type': 'error', 'error': {'type': 'invalid_request_error', 'message': "You're out of extra usage..."}, 'request_id': 'req_011CbPw84JVcAuAgPxZCJa1U'}

Questions for maintainers

• Does Hermes call the OAuth-backed Anthropic endpoint differently from Claude Code itself? (E.g. wrong anthropic-beta header, wrong endpoint path, missing client identifier?) The dumped request shows POST https://api.anthropic.com/chat/completions rather than /v1/messages — is that intentional when authenticating with a Pro/Max OAuth token, or does that route accounting to a different (and apparently exhausted) bucket?
• Are there known scope/header changes needed for manual:hermes_pkce-sourced credentials vs claude_code-sourced ones?
• Is there a recommended way to confirm whether the OAuth identity Hermes is using is actually billed against the Max plan vs. some "extra usage" pool that depletes separately?

Additional context

• Same behavior was observed previously with the claude_code-sourced credential (imported from ~/.claude/.credentials.json) before this fresh login, so the failure is not specific to the new hermes_pkce credential.
• Switching back to the imported claude_code credential reproduces the same error.

Steps to Reproduce

1. Start with a clean Claude Pro/Max account (no recent Claude Code / Hermes activity).
2. Remove any existing anthropic credentials: hermes auth remove anthropic <label>
3. Add a fresh OAuth credential: hermes auth add anthropic --type oauth --no-browser --manual-paste
4. Complete the Pro/Max authorization flow at https://claude.ai/oauth/authorize?... (standard Claude Code OAuth client 9d1c250a-..., scopes org:create_api_key user:profile user:inference).
5. Paste the returned code; credential is stored in ~/.hermes/auth.json (auth_type: oauth, source: manual:hermes_pkce).
6. Restart hermes-gateway (so it picks up the new credential).
7. Send any message — e.g. via Mattermost platform, or hermes -z "ping".

Expected Behavior

Request succeeds (or, at worst, fails with a token/scope error that points to a real configuration problem).

Actual Behavior

Actual

Request reaches Anthropic and returns: HTTP 400 { "type": "error", "error": { "type": "invalid_request_error", "message": "You're out of extra usage. Add more at claude.ai/settings/usage and keep going." }, "request_id": "req_011CbPw84JVcAuAgPxZCJa1U" }

Affected Component

CLI (interactive chat)

Messaging Platform (if gateway-related)

N/A (CLI only)

Debug Report

2026-05-25 20:40:21,514 INFO gateway.run: inbound message: platform=mattermost user=applegater chat=usccd6fe8fb83xnfn6yx14u33h msg='ping'
2026-05-25 20:40:23,650 INFO gateway.run: response ready: platform=mattermost chat=usccd6fe8fb83xnfn6yx14u33h time=2.1s api_calls=1 response=222 chars
2026-05-25 20:40:23,651 INFO gateway.run: Skipping transcript persistence for context-overflow failure in session 20260525_184718_7d021b59 to prevent session growth loop.
2026-05-25 20:40:23,657 INFO gateway.platforms.base: [Mattermost] Sending response (222 chars) to usccd6fe8fb83xnfn6yx14u33h
2026-05-25 20:44:16,957 INFO gateway.memory_monitor: [MEMORY] rss=163MB gc=(405, 9, 3) threads=5 uptime=300s

Operating System

Ubuntu 24.0.4

Python Version

3.11.15

Hermes Version

0.14.0

Additional Logs / Traceback (optional)

Gateway log excerpt

  2026-05-25 20:40:21 INFO  gateway.run: inbound message: platform=mattermost ... msg='ping'
  2026-05-25 20:40:23 WARNING agent.conversation_loop: API call failed (attempt 1/3) error_type=BadRequestError provider=anthropic
  base_url=https://api.anthropic.com model=claude-sonnet-4-6 summary=HTTP 400: You're out of extra usage. Add more at
  claude.ai/settings/usage and keep going.
  2026-05-25 20:40:23 ERROR   agent.conversation_loop: Non-retryable client error: Error code: 400 - {'type': 'error', 'error': {'type':
  'invalid_request_error', 'message': "You're out of extra usage..."}, 'request_id': 'req_011CbPw84JVcAuAgPxZCJa1U'}

Root Cause Analysis (optional)

No response

Proposed Fix (optional)

No response

Are you willing to submit a PR for this?

• I'd like to fix this myself and submit a PR