From f67e9651cfe32e41c99e75e4cfc388a8e88708e3 Mon Sep 17 00:00:00 2001
From: "Jakub A. W" <jakubwasek@gmail.com>
Date: Thu, 16 Apr 2026 14:16:51 +0200
Subject: [PATCH 1/2] docs(features): add failover page

---
 docs/docs.json             |  3 +-
 docs/features/failover.mdx | 68 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 docs/features/failover.mdx

diff --git a/docs/docs.json b/docs/docs.json
index bc0d63bf..3ac99f1c 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -38,7 +38,8 @@
                         "pages": [
                             "features/aliases",
                             "features/user-path",
-                            "features/cache"
+                            "features/cache",
+                            "features/failover"
                         ]
                     },
                     {
diff --git a/docs/features/failover.mdx b/docs/features/failover.mdx
new file mode 100644
index 00000000..f16dc870
--- /dev/null
+++ b/docs/features/failover.mdx
@@ -0,0 +1,68 @@
+---
+title: "Failover"
+description: "Configure GoModel failover with manual rules, understand experimental auto mode, and know when fallback attempts run."
+icon: "shuffle"
+keywords: ["failover", "fallback"]
+---
+
+## Overview
+
+GoModel exposes failover through the `fallback` config block.
+
+When a request fails, GoModel can retry it against alternate models. For
+predictable behavior, use manual mode.
+
+## Manual Mode
+
+Manual mode is the recommended mode today.
+
+```yaml
+fallback:
+  default_mode: "manual"
+  manual_rules_path: "config/fallback.json"
+```
+
+`config/fallback.json` is an ordered JSON map:
+
+```json
+{
+  "gpt-4o": [
+    "azure/gpt-4o",
+    "gemini/gemini-2.5-pro"
+  ]
+}
+```
+
+GoModel tries the listed candidates in order and stops on the first success.
+Use bare model names like `gpt-4o` or provider-qualified selectors like
+`azure/gpt-4o`.
+
+If needed, you can override the mode per model with `fallback.overrides`.
+
+## Auto Mode
+
+<Note>
+  `auto` mode is experimental right now.
+</Note>
+
+```yaml
+fallback:
+  default_mode: "auto"
+  manual_rules_path: "config/fallback.json"
+```
+
+Auto mode keeps any manual candidates first, then appends up to five extra
+candidates from the current model registry. It prefers models with the same
+request category, similar rankings, overlapping capabilities, and the same
+family when possible.
+
+## When It Runs
+
+Failover is attempted only after the primary request returns:
+
+- `5xx`
+- `429`
+- model unavailable, unsupported, or not found style errors
+
+It currently applies to translated `/v1/chat/completions` and `/v1/responses`
+requests, not `/v1/embeddings`.

From 205b311d630b071a1470adaf918cee1a612295bd Mon Sep 17 00:00:00 2001
From: "Jakub A. W" <jakubwasek@gmail.com>
Date: Thu, 16 Apr 2026 18:36:43 +0200
Subject: [PATCH 2/2] docs(features): clarify failover rule ordering

---
 docs/features/failover.mdx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/features/failover.mdx b/docs/features/failover.mdx
index f16dc870..8e41705b 100644
--- a/docs/features/failover.mdx
+++ b/docs/features/failover.mdx
@@ -22,7 +22,8 @@ fallback:
   manual_rules_path: "config/fallback.json"
 ```
 
-`config/fallback.json` is an ordered JSON map:
+`config/fallback.json` is a JSON object where each model entry contains an
+ordered candidate list (array); top-level keys are not ordered:
 
 ```json
 {
@@ -33,6 +34,8 @@ fallback:
 }
 ```
 
+The order-sensitive part is the array under each model entry.
+
 GoModel tries the listed candidates in order and stops on the first success.
 Use bare model names like `gpt-4o` or provider-qualified selectors like
 `azure/gpt-4o`.