fix(agent): classify Anthropic "extra usage" 400 as billing, not format_error

[aldoeliacim]

What & why

When a Claude subscription must enable extra usage to keep serving, native Anthropic returns HTTP 400 with a body like:

Third-party apps now draw from your extra usage. To continue, enable extra usage in your account settings.

_classify_400 had no pattern for this, so it fell through to the generic format_error bucket. Two real consequences:

1. Wrong user guidance — the user sees an opaque "format error" instead of the actionable billing/entitlement guidance (_print_billing_or_entitlement_guidance).
2. No credential rotation — billing sets should_rotate_credential=True; format_error does not. A multi-credential pool never rotates to another entry on this signal.

Both _classify_400 (status path) and _classify_by_message (no-status sibling path) are fixed, so the whole class is covered rather than one call site.

The fix

Add a dedicated _ENTITLEMENT_PATTERNS list and classify these messages as FailoverReason.billing (retryable=False, should_rotate_credential=True, should_fallback=True).

Patterns are deliberately specific to an account action on extra usage (draw from your extra usage, enable extra usage, exceed your extra usage, extra usage allowance) so they do not collide with the existing 429 rolling-cap / long-context tier gate ("extra usage" + "long context" → long_context_tier, retryable). The no-status path additionally guards on "long context" explicitly.

How to test

from agent.error_classifier import classify_api_error, FailoverReason
# build a 400 whose body message is:
#   "Third-party apps now draw from your extra usage. ..."
# classify_api_error(...).reason  -> FailoverReason.billing (was format_error)
# .should_rotate_credential       -> True (was False)

New test tests/agent/test_entitlement_extra_usage_classification.py covers:

• three entitlement phrasings → billing + rotate + fallback
• no-collision invariant: 429 extra usage + long context stays long_context_tier
• control: real credit balance billing still billing

tests/agent/test_error_classifier.py (161 tests) stays green.

Platforms

Logic-only change in agent/error_classifier.py (string matching + classification flags); no OS-specific paths. Tested on Linux.

---

Rebased onto current main (2026-06-26). Conflict in agent/error_classifier.py: main added an _OVERLOADED_PATTERNS block at the same no-status classification point; resolved by ordering overloaded → entitlement → generic billing so the transient-overload check runs first and the specific entitlement match still wins over generic _BILLING_PATTERNS. Verified: test_error_classifier + entitlement + failover = 180 passed.

[Copilot]

Pull request overview

This PR updates Hermes’ API error classification to recognize Anthropic “extra usage” entitlement errors that arrive as HTTP 400 and route them to the billing failover bucket (instead of format_error), enabling correct user guidance and credential rotation behavior.

Changes:

• Add _ENTITLEMENT_PATTERNS and classify matching Anthropic 400 errors as FailoverReason.billing (non-retryable, rotate credential, allow fallback).
• Extend the no-status message-only classifier to also treat these entitlement messages as billing, while explicitly avoiding collision with the 429 long-context tier gate.
• Add a focused test suite covering entitlement phrasings and the “no collision” invariant with the existing 429 long_context_tier behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
agent/error_classifier.py	Adds entitlement-specific pattern matching to classify certain Anthropic 400s (and message-only cases) as billing.
tests/agent/test_entitlement_extra_usage_classification.py	Adds regression tests for entitlement message classification and guards against misclassifying the 429 long-context tier gate.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.