Error Classification & Retry Cascade

ClawRouter classifies upstream errors to determine the correct recovery action. Each error type triggers a specific behavior in the retry cascade.

Version 1.0.18

---

Error Classification Reference

---

Retry Cascade (Exact Order)

When a request fails, ClawRouter follows this exact retry cascade:

1. REQUEST_ERROR (400/413/422/499) > Return to client immediately (will fail with any key).
2. OVERLOADED (503/529) > Wait 2 seconds, retry same key (up to 2 inner retries).
3. MODEL_ERROR (404/400/401/403 with model or subscription patterns) > Try next model from provider_models if model_fallback_enabled (same key). Repeated model failures trip the model circuit breaker, after which the model is skipped entirely -- see Model Fallback.
4. AUTH_ERROR / QUOTA_EXHAUSTED / RATE_LIMIT / SERVER_ERROR / TIMEOUT / NETWORK_ERROR > Try next key.
5. All keys exhausted > Trigger Provider Fallback Chain (tried in priority order).
6. All fallback providers exhausted > Return error to client.

---

Key Backoff & Error Handling Summary

---

Window Quota vs Hard Billing

Two kinds of "out of quota" errors exist, and ClawRouter treats them very differently:

• Window quota (QUOTA_EXHAUSTED) -- self-resetting cycles: Kimi Coding's 5-hour/weekly/monthly windows, Z.AI's 5-hour/7-day windows (codes 1308/1310/1316-1321), OpenAI monthly quota. The key is valid; its quota window is simply full. The key enters a long backoff and is never disabled. It recovers automatically when the window resets.
• Hard billing (AUTH_ERROR) -- the account has no money left: HTTP 402, "credit balance too low", MiniMax insufficient_balance, Z.AI code 1113 / insufficient_quota (a 429!). These disable the key permanently, like any auth error.

The distinction matters because window-quota errors often arrive on auth-looking statuses -- Kimi Coding returns HTTP 403 access_terminated_error, not 429 -- and naively treating every 403 as an auth error would disable a perfectly good key.

How the Quota Cooldown Is Calculated

Cooldowns are per-key and window-accurate -- not a shared blanket cooldown. When a key hits QUOTA_EXHAUSTED, ClawRouter picks the reset time in this order:

1. The key's saved quota snapshot -- every successful quota probe (Quota tab or traffic-time) persists that key's windows and reset times. The error text is matched to a window kind (5-hour vs weekly), so a key that exhausts its 5-hour window cools down until its 5-hour reset, and a weekly exhaustion cools down until its weekly reset. Two keys tripping different windows at the same moment get different, accurate cooldowns.
2. A reset time parsed from the error body (capped at quota_backoff_s).
3. Monthly billing-cycle detection -- a "usage limit ... next cycle" style body means the monthly cycle is exhausted even when 5-hour/weekly quota shows available. The message is "Monthly usage cycle exhausted"; the key is not disabled -- it is retried in ~10-day steps anchored to its last successful use until the cycle renews.
4. A live usage-endpoint probe for the actual reset time.
5. Default quota_backoff_s (1800 seconds, configurable in Settings) when nothing else is known.

Trusted reset times (snapshot, probe, monthly anchor) bypass the quota_backoff_s cap -- a weekly window really is days long -- with a 30-day sanity ceiling.

---

Provider-Specific Quirks

Some providers return non-standard HTTP status codes that ClawRouter handles specially:

Z.AI Business Codes

Z.AI returns a numeric-string code in error.code that overrides the HTTP status (almost everything arrives as 429). ClawRouter classifies by code, per Z.AI's published error table:

Dead-key trap: Z.AI's monitor endpoint returns HTTP 200 with {"code":1000,"msg":"Authentication Failed","success":false} for a dead key. ClawRouter detects this envelope (auth-family codes 1000-1005, with or without the message) and treats it exactly like a real 401.