From b8c4f44c1f3a59e1a66e401838ac9675f6905e5a Mon Sep 17 00:00:00 2001 From: Bryan Nie Date: Sun, 1 Mar 2026 16:11:54 +0800 Subject: [PATCH] docs: add guide for speeding up fallback with proxy APIs --- docs/reference/configuration.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index c01865a5f..b251f181d 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -558,6 +558,23 @@ Auto-switches to backup models on API errors. | `timeout_seconds` | `30` | Seconds before forcing next fallback. **Set to `0` to disable timeout-based escalation and provider retry message detection.** | | `notify_on_fallback` | `true` | Toast notification on model switch | +#### Speeding Up Fallback (Proxy APIs) + +If you are using a proxy API provider, they may return different error codes (e.g., `401`, `403`, `404`) for quota exhaustion or model unavailability. To make fallback trigger instantly without waiting for long timeouts: + +```jsonc +{ + "runtime_fallback": { + "enabled": true, + // Add your proxy's specific error codes to retry_on_errors + "retry_on_errors": [400, 401, 403, 404, 429, 500, 502, 503, 504], + "max_fallback_attempts": 3, + "cooldown_seconds": 15, // Shorter cooldown + "timeout_seconds": 10 // Detect hung proxy requests faster + } +} +``` + Define `fallback_models` per agent or category: ```json