[Bug]: OAuth Pro/Max credential returns "out of extra usage" 400 immediately after fresh login, despite empty/unused account quota

[X4Applegate]

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
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
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

[teknium1]

Closing as working as intended — won't implement.

These all trace back to making Claude Pro/Max/Team OAuth credentials draw from plan limits for programmatic (Agent-SDK / third-party) traffic. As of Anthropic's mid-June 2026 change, that traffic is metered as extra usage, not subscription plan usage — this is the intended billing behavior, not a Hermes bug.

The only way to make these requests bill on-plan again is to present as the genuine first-party Claude CLI/Agent-SDK surface (e.g. injecting the x-anthropic-billing-header / cc_entrypoint=sdk-cli system block, spoofing the client identity). That is explicitly the spoof-filter Anthropic is enforcing against, and shipping it would put users at real risk of account suspension. We are not going to ship a mitigation whose mechanism is "evade the provider's usage-attribution filter."

If you want to use an Anthropic OAuth subscription with Hermes, on-plan billing for programmatic use is not currently supported by Anthropic. Use a standard x-api-key API key (ANTHROPIC_API_KEY) for API access, or expect requests to draw from extra-usage credits.

The underlying endpoint constants (console.anthropic.com vs platform.claude.com) are moot here: even with corrected endpoints and valid tokens, on-plan OAuth inference still returns the "extra usage, not plan limits" 400 by design. Closing the endpoint-correction issues in this same cluster for the same reason.

Thanks for the detailed reports and reproductions regardless — the A/B tables and endpoint tracing were genuinely useful for confirming the behavior is provider-side and intentional.

[X4Applegate]

Thank you for your time explaining and it does explain lot and understood. I appericate it. And we will start paying extra usage and move forwarding. Great work on this hermes agent