#16307: fix: surface billing/auth FailoverErrors as user-friendly messages
agents
stale
size: M
trusted-contributor
Cluster:
Model Fallbacks and Rate Limiting
Root cause: When `FailoverError` with billing or auth reason is thrown after all models fail, the catch block in `runAgentTurnWithFallback` falls through to the generic "Agent failed before reply" handler instead of producing a clean, actionable error message.
Fix: Add explicit `isFailoverError` check before the generic fallback, routing billing errors to `formatBillingErrorMessage()` and auth errors to a provider-specific authentication failure message.
Test: 5 cases covering billing/auth with and without provider name, verifying clean user-facing messages and absence of generic "Agent failed before reply" text.
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Improved error handling for billing and authentication failures by surfacing `FailoverError` instances with specific, user-friendly messages instead of falling through to the generic "Agent failed before reply" handler.
Key changes:
- Added explicit `isFailoverError` check in `agent-runner-execution.ts:548-567` before the generic fallback handler
- Routes billing errors to `formatBillingErrorMessage()` and auth errors to `formatAuthErrorMessage()` with provider-specific context when available
- Updated `pi-embedded-runner/run.ts:881` to use `formatAuthErrorMessage()` instead of generic "LLM request unauthorized." text
- Added comprehensive test coverage with 5 test cases covering both billing and auth scenarios with/without provider names
- Tests verify clean messages and absence of generic error text
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation is straightforward, well-tested, and follows existing patterns. The change adds specific error handling for FailoverError cases before falling through to generic handlers, which improves user experience without altering any core logic. Test coverage validates all code paths including with/without provider names for both billing and auth scenarios.
- No files require special attention
<sub>Last reviewed commit: 244a1f7</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#13658: fix: silent model failover with fallback notification
by taw0002 · 2026-02-10
84.3%
#15109: fix: distinguish transient API errors from billing errors
by jwchmodx · 2026-02-13
81.5%
#21152: fix(agents): throw FailoverError for unknown model so fallback chai...
by Mellowambience · 2026-02-19
80.5%
#9427: fix: trigger model fallback on all 4xx HTTP errors
by dbottme · 2026-02-05
79.6%
#23520: fix: trigger failover on Anthropic insufficient_quota (HTTP 400) (#...
by dissaozw · 2026-02-22
79.3%
#9173: Fix: Improve error messaging for API rate limits and billing errors
by vishaltandale00 · 2026-02-04
79.1%
#19252: fix(agents): continue model fallback on failover text payloads
by mahsumaktas · 2026-02-17
79.0%
#23502: fix: Anthropic insufficient_quota HTTP 400 does not trigger failove...
by stakeswky · 2026-02-22
78.7%
#12314: fix: treat HTTP 5xx server errors as failover-worthy
by hsssgdtc · 2026-02-09
78.2%
#10178: fix: trigger fallback when model resolution fails with unknown model
by Yida-Dev · 2026-02-06
77.6%