Fallback

provider.fallback listet Ersatzmodelle auf, die der Reihe nach versucht werden, wenn das Hauptmodell upstream scheitert.

Konfiguration

fallback erwartet ein Array von Modell-IDs und steht auf derselben Ebene wie type unter provider. Höchstens 3 Modelle; darüber hinaus liefert die Anfrage 400.

cURL

Terminal


curl https://api.ofox.run/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"]
      }
    }
  }'

Python

fallback.py


client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "..."}],
    extra_body={
        "extra_body": {
            "provider": {
                "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"],
            }
        }
    },
)

TypeScript

fallback.ts


await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: '...' }],
  extra_body: {
    provider: {
      fallback: ['openai/gpt-5.5', 'google/gemini-2.5-pro'],
    },
  },
} as any)

Bei den offiziellen OpenAI-SDKs muss extra_body als wörtlicher Schlüssel im Request-Body vorhanden sein. Das TypeScript-SDK sendet es so, wie es im Parameterobjekt steht. Das Argument extra_body= des Python-SDK verschmilzt seinen Inhalt mit der obersten Ebene des Bodys; der Schlüssel muss dort also eine Ebene tiefer verschachtelt oder stattdessen als Request-Header übergeben werden.

Was einen Fallback auslöst

Ein Fallback deckt nur Fehler ab, die auftreten, nachdem das Routing einen Kanal gewählt hat:

Situation	Verhalten
Der Upstream-Anbieter liefert einen Fehler	Fallback — die gelisteten Modelle werden der Reihe nach versucht, der erste Erfolg wird zurückgegeben
Das Routing selbst scheitert (Modell existiert nicht, oder der festgelegte Anbieter stellt es nicht bereit)	Kein Fallback — die Anfrage endet sofort

Die zweite Zeile sollte man deutlich aussprechen: provider.type auf einen Anbieter zu setzen, der das Modell nicht bereitstellt, liefert 400 provider_type_unavailable, und ein nicht existierendes Modell liefert 404 model_not_found. Beides erreicht die Fallback-Liste nicht. Welche Upstream-Fehler tatsächlich einen Fallback auslösen, richtet sich nach dem Verhalten des Gateways und nicht nach einer festen Liste.

Kombination mit einem festgelegten Anbieter

fallback und type lassen sich gemeinsam senden: type schränkt ein, wo das Hauptmodell läuft, fallback deckt ab, was passiert, wenn es scheitert:


{
  "model": "anthropic/claude-sonnet-5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-5.5"]
    }
  }
}

Vollständige Feldreferenz unter Provider-Routing.

Häufige Fehler

`error.type`	Auslöser
`invalid_request_error`	Die `fallback`-Liste enthält mehr als 3 Modelle.

Best Practices

Ersatzmodelle mit vergleichbarer Leistungsfähigkeit wählen — damit die Ausgabequalität nach einem Fallback gleich bleibt.
Herstellerübergreifend wählen — Modelle eines Herstellers fallen häufig gemeinsam aus.
Die Häufigkeit beobachten — häufige Fallbacks sind ein Zeichen, das Hauptmodell zu wechseln.