LLM API Fallback Routing: Ein Playbook für produktives Failover

Fallback-Routing für LLM-APIs klingt einfach, bis der erste echte Vorfall eintritt: einen Fehler abfangen, Modelle wechseln und es erneut versuchen. In der Produktion kann diese Regel ein Problem bei einem Anbieter in doppelte Tool-Aufrufe, fehlerhaftes JSON, gemischte Streaming-Ausgaben, außer Kontrolle geratene Retry-Traffic oder eine Antwort verwandeln, die technisch erfolgreich ist, aber das Produktvertrag nicht mehr erfüllt.

Ein sichereres Design behandelt Fallback als begrenzte Zustandsmaschine, nicht als Liste von Backup-Modellnamen. Jede Anfrage durchläuft eine kleine Menge an Entscheidungen:

1. Ist der Fehler erneut versuchbar?
2. Ist es sicher, diese Anfrage zu wiederholen?
3. Soll der nächste Versuch dasselbe Ziel oder ein anderes verwenden?
4. Kann der Fallback den erforderlichen Vertrag beibehalten?
5. Hat die Anfrage bereits Ausgabe oder Seiteneffekte erzeugt?
6. Sind die End-to-End-Latenz und das Versuchslimit ausgeschöpft?

Dieses Playbook überführt diese Fragen in eine Fehler-Matrix, Routing-Richtlinie, TypeScript-Controller, Testplan und Rollout-Checkliste für Multi-Provider-LLM-Anwendungen.

Die vier Aktionen hinter zuverlässigem LLM-API-Fallback-Routing

Leiten Sie nicht jeden Fehler in dieselbe Retry-Schleife. Ein Produktionsrouter benötigt vier unterschiedliche Aktionen.

Die Unterscheidung zwischen Failover und Fallback ist wichtig. Failover behält den logischen Modellvertrag bei und ändert die Infrastruktur. Fallback ändert das Modell oder die Fähigkeitsstufe. Failover ist in der Regel der risikoärmere Schritt.

Wenn Sie das breitere Design des Request-Pfads rund um Aliase, Health-Scoring, Billing und Observability benötigen, beginnen Sie mit dem Leitfaden zur Architektur eines AI API Gateways. Dieser Artikel konzentriert sich auf den Controller, der nach der Auswahl eines Ziels ausgeführt wird.

Erstellen Sie eine Fehler-zu-Aktion-Matrix, bevor Sie Retry-Code schreiben

Provider-SDKs stellen unterschiedliche Exception-Klassen und Response-Bodies bereit, aber der Router sollte sie in eine kleine interne Taxonomie normalisieren.

Die offizielle Dokumentation der Provider unterstreicht, warum eine Normalisierung notwendig ist. Anthropic dokumentiert separate Rate-Limit-, API- und Überlastungsfehler und weist darauf hin, dass eine Streaming-Anfrage auch nach einer zunächst erfolgreichen Antwort noch fehlschlagen kann. OpenAI trennt ebenfalls zwischen ungültigen Anfragen, Rate Limits und serverseitigen Fehlern. Ihre Anwendung sollte providerspezifische Signale in stabile interne Entscheidungen übersetzen, anstatt Providernamen durchgehend in die Geschäftslogik einzubetten.

Setzen Sie ein einziges Retry-Budget um die gesamte Anfrage herum

Wiederholungen existieren oft an mehreren Stellen gleichzeitig: im HTTP-Client, im Provider-SDK, im Gateway, im Hintergrundjob und im Anwendungservice. Wenn jede Schicht drei Versuche ausführt, kann eine einzelne Benutzeraktion in weit mehr Upstream-Aufrufe münden, als das Team beabsichtigt hat.

Das sicherere Muster ist:

• Wählen Sie eine Schicht, die die LLM-Retries und das Fallback verantwortet.
• Setzen Sie eine einzige End-to-End-Deadline für die Benutzeranfrage oder den Job.
• Setzen Sie eine maximale Anzahl von Upstream-Versuchen.
• Reservieren Sie einen Teil der Deadline für das Fallback-Ziel.
• Verwenden Sie exponentielles Backoff mit Jitter für vorübergehende Fehler.
• Brechen Sie ab, wenn die verbleibende Zeit keinen weiteren sinnvollen Versuch mehr zulässt.

Die AWS-Richtlinien zu Timeouts, Retries, Backoff und Jitter beschreiben, wie Wiederholungen Überlast verstärken können, und empfehlen ein begrenztes Verhalten statt einer ständigen sofortigen Wiederholung. Dasselbe Prinzip gilt für Modell-APIs, bei denen ein unter Last stehender Provider am wenigsten in der Lage ist, synchronisierten Retry-Traffic aufzufangen.

Ein praktisches interaktives Budget könnte eher als Policy denn als fest codierte Sleeps ausgedrückt werden:

type RetryBudget = {
  deadlineMs: number;
  maxAttempts: number;
  maxSameTargetAttempts: number;
  reserveForFallbackMs: number;
};

Die genauen Werte hängen vom Produkt ab. Eine Chat-Oberfläche, ein Coding-Agent, ein Batch-Evaluator und ein asynchroner Video-Workflow sollten nicht dasselbe Budget teilen.

Verwenden Sie Circuit Breaker, um das Routing in bekannte Ausfälle zu stoppen

Ein Circuit Breaker verhindert, dass jede neue Anfrage denselben Ausfall erneut entdeckt.

Die Standardzustände sind:

• Closed: Anfragen laufen normal, während der Router Fehler und Latenz misst.
• Open: Das Ziel ist vorübergehend nicht zulässig, weil sein jüngstes Verhalten einen Schwellenwert überschritten hat.
• Half-open: Eine kleine Anzahl von Probe-Anfragen testet, ob sich das Ziel erholt hat.

Azures Circuit-Breaker-Muster beschreibt diesen Closed/Open/Half-open-Lebenszyklus. Für LLM-Routing sollte der Breaker-Schlüssel spezifisch genug sein, um die fehlerhafte Oberfläche zu isolieren. Nützliche Dimensionen sind Provider, Modell, Region, Deployment, Konto und Fähigkeit. Ein Text-Completion-Deployment kann gesund sein, während ein Tool-Calling-Pfad oder ein regionaler Endpunkt ausfällt.

Öffnen Sie Circuits nicht bei jedem Client-Fehler. Ungültige Authentifizierung, fehlerhafte Anfragen, Kontextüberlauf und Policy-Ablehnung sagen in der Regel mehr über die Anfrage als über die Provider-Gesundheit aus. Breaker sollten primär auf vorübergehende Infrastruktursignale wie Verbindungsfehler, Timeouts, Überlastung und Serverfehler reagieren.

Bewahren Sie einen Fähigkeitsvertrag über Modelle hinweg

Ein Fallback-Modell ist nicht allein deshalb sicher, weil es eine OpenAI-kompatible Anfrage akzeptiert. Definieren Sie den Minimalvertrag für jeden Route-Alias.

route: support-agent-v3
requires:
  modalities: [text]
  streaming: true
  tools: true
  parallel_tool_calls: false
  structured_output: json_schema
  context_window_min: 64000
  max_output_tokens_min: 4000
quality_gates:
  task_success_rate_min: 0.94
  schema_valid_rate_min: 0.995
policy:
  same_model_failover_first: true
  cross_model_fallback_allowed: true

Bevor Sie ein Ziel zum Fallback-Set hinzufügen, testen Sie mindestens:

• Unterstützte Request-Parameter
• Tool-Definition und Tool-Call-Verhalten
• Gültigkeit strukturierter Ausgaben
• Form des Streaming-Events
• Kontext- und Ausgabelimits
• Für die Anwendung angemessenes Sicherheitsverhalten
• Felder zur Token-Bilanzierung, die von Kostenkontrollen verwendet werden
• Latenz und Qualität bei repräsentativen Prompts

Dieser vertragsorientierte Ansatz ist besonders wichtig für Workflows, die mehrere Modalitäten übergreifen. Der Leitfaden zum multimodalen Agent-Routing behandelt zusätzliche Prüfungen für Text-, Bild-, Audio- und Video-Routen.

Ein TypeScript-Fallback-Controller

Das folgende Beispiel ist bewusst anbieterneutral gehalten. Es setzt voraus, dass Upstream-Adapter Fehler und Antworten normalisieren, bevor die Routing-Schicht sie sieht.

type FailureKind =
  | "connect"
  | "timeout"
  | "rate_limit"
  | "overloaded"
  | "server_error"
  | "invalid_request"
  | "auth"
  | "policy"
  | "context_overflow"
  | "partial_stream"
  | "unknown";

type Target = {
  id: string;
  contractId: string;
  healthy: boolean;
  circuit: "closed" | "open" | "half_open";
};

type RequestState = {
  attempt: number;
  sameTargetAttempts: number;
  deadlineAt: number;
  outputStarted: boolean;
  sideEffectsPossible: boolean;
};

function canReplay(state: RequestState): boolean {
  return !state.outputStarted && !state.sideEffectsPossible;
}

function isTransient(kind: FailureKind): boolean {
  return [
    "connect",
    "timeout",
    "rate_limit",
    "overloaded",
    "server_error",
  ].includes(kind);
}

function chooseNextAction(
  kind: FailureKind,
  state: RequestState,
  current: Target,
  equivalent: Target | undefined,
  fallback: Target | undefined,
) {
  if (!canReplay(state) || kind === "partial_stream") return { type: "stop" };

  if (!isTransient(kind)) return { type: "stop" };

  if (state.attempt >= 3 || Date.now() >= state.deadlineAt) {
    return { type: "stop" };
  }

  if (
    state.sameTargetAttempts < 1 &&
    current.circuit === "closed" &&
    current.healthy
  ) {
    return { type: "retry", target: current };
  }

  if (equivalent?.healthy && equivalent.circuit !== "open") {
    return { type: "failover", target: equivalent };
  }

  if (
    fallback?.healthy &&
    fallback.circuit !== "open" &&
    fallback.contractId === current.contractId
  ) {
    return { type: "fallback", target: fallback };
  }

  return { type: "stop" };
}

Produktionscode benötigt außerdem verzögerte Ausführungen mit Jitter, Weitergabe von Abbrüchen, Request-IDs, Updates des Circuit Breakers, Telemetrie und anbieter-/adapter-spezifisches Parsing von Fehlern. Die wichtige Eigenschaft ist, dass Replay-Sicherheit und Vertragskompatibilität vor der Auswahl eines weiteren Ziels geprüft werden.

Behandle Streaming-Fallback als separates Protokoll

Streaming schafft eine harte Grenze: Sobald Inhalt den Client erreicht, kann das Gateway nicht mehr so tun, als wäre der Versuch nie passiert.

Wenn der Upstream ausfällt, bevor das erste Ereignis weitergeleitet wird, kann ein Retry oder Fallback dennoch transparent sein. Nachdem das erste Token, Tool-Delta, Bildereignis oder Audio-Chunk zugestellt wurde, birgt automatisches Modellwechseln das Risiko, zwei inkompatible Antworten zu vermischen.

Verwenden Sie eine dieser expliziten Strategien:

1. Stream klar fehlschlagen lassen. Geben Sie ein stabiles Fehlerereignis mit der Request-ID zurück und lassen Sie den Client einen Retry anbieten.
2. Vor der Freigabe puffern. Validieren Sie bei kurzen strukturierten Antworten das vollständige Ergebnis, bevor Sie es downstream senden. Das geht zulasten der Time-to-first-token.
3. Resume auf Anwendungsebene implementieren. Starten Sie einen neuen Turn mit explizitem Kontext, der sagt, dass die vorherige Antwort unterbrochen wurde. Behandeln Sie es als neue Modellgenerierung, nicht als Fortsetzung desselben Byte-Streams.

Verketten Sie Ausgaben zweier Modelle nicht stillschweigend.

Trennen Sie die Zuverlässigkeit von Tool-Calls von der Zuverlässigkeit von Model-Calls

Ein LLM-Request kann erneut abgespielt werden, während das von ihm ausgewählte Tool dies nicht kann. Eine Zahlung, E-Mail, Bereitstellung, ein Datenbank-Write oder das Erstellen eines Tickets kann erfolgreich sein, auch wenn die Modellverbindung ausfällt, bevor die Anwendung das Ergebnis aufzeichnet.

Schützen Sie Tools mit schreibenden Side Effects mit:

• Einem Idempotency-Key, der aus der Benutzeraktion abgeleitet ist, nicht aus dem Provider-Versuch
• Einem dauerhaften Protokoll der Tool-Ausführung
• Deduplication an der Tool-Grenze
• Einer klaren Unterscheidung zwischen planned, started, succeeded und unknown
• Manueller Überprüfung bei unsicheren Side Effects mit hoher Auswirkung

Wenn Side Effects möglich sind und ihr Ergebnis unbekannt ist, stoppen Sie automatisches Fallback. Klären Sie zuerst den Tool-Zustand ab.

Beobachten Sie Fallback als Produktergebnis

Eine niedrige Fehlerquote des Providers beweist nicht, dass Fallback funktioniert. Verfolgen Sie das gesamte Routenergebnis.

Protokollieren Sie für jeden Versuch einen Routengrund: ausgewähltes Ziel, normalisierter Fehler, Retry-Verzögerung, Circuit-Status, Fallback-Grund, verbleibende Request-Deadline und Endergebnis. Vermeiden Sie das Protokollieren sensibler Prompts oder Ausgaben, sofern die Datenrichtlinie des Produkts dies nicht ausdrücklich erlaubt.

Testen Sie die Fehlerpfade, bevor Sie automatisches Fallback aktivieren

Führen Sie Failure Injection in einer Staging-Umgebung durch und rollen Sie die Policy dann per Canary in der Produktion aus.

Transport- und Provider-Tests

• Trennen Sie die Verbindung vor den Antwort-Headern.
• Geben Sie wiederholte Rate-Limits mit und ohne Retry-Hinweis zurück.
• Simulieren Sie Überlast und Serverfehler.
• Verzögern Sie das primäre Ziel, bis die Request-Deadline nahezu ausgeschöpft ist.
• Öffnen Sie einen Ziel-Circuit und prüfen Sie, ob der Traffic zu einem zulässigen Route wechselt.
• Stellen Sie das Ziel wieder her und prüfen Sie, ob Half-Open-Probes nicht zu früh den vollständigen Traffic wiederherstellen.

Contract tests

• Entfernen Sie ein erforderliches Tool aus dem Fallback-Adapter.
• Geben Sie ungültige strukturierte Ausgabe zurück.
• Ändern Sie die Form eines Streaming-Events.
• Überschreiten Sie Kontext- oder Ausgabelimits.
• Vergleichen Sie die Fallback-Qualität auf einem festen Evaluierungsset.

Replay-safety tests

• Fehlschlagen vor und nach dem ersten gestreamten Event.
• Fehlschlagen, nachdem ein Write-side-Tool begonnen hat.
• Verwenden Sie denselben Idempotency-Key erneut.
• Brechen Sie die Client-Anfrage ab, während der Fallback-Versuch noch aussteht.

Der Test besteht nur dann, wenn der Router die erwartete Aktion auswählt und festhält, warum.

Where Flatkey fits

Flatkey stellt einen API-Schlüssel und eine mit OpenAI kompatible Base-URL für unterstützte Modelle bereit, mit zentralisiertem Usage und Billing. Das schafft eine stabile Integrationsgrenze für den Zugriff auf mehrere Modelle und das Routing.

Application Teams sollten weiterhin den in diesem Playbook beschriebenen Route-Contract verantworten: welche Fehler erneut versucht werden dürfen, welche Ziele als äquivalent gelten, ob Cross-Model-Fallback erlaubt ist, wie Tools dedupliziert werden und welche Qualitätsgrenze eine wiederhergestellte Antwort erfüllen muss.

Für den kürzesten Integrationspfad verwenden Sie den Flatkey integration starter. Wenn Sie einen bestehenden Client migrieren, deckt die OpenAI-compatible API gateway checklist Base URL, Parameter, Streaming und die Verifizierung der Fehlerform ab.

Production rollout checklist

• Normalisieren Sie Provider-Fehler in eine stabile interne Taxonomie.
• Definieren Sie Retry-, gleichwertige Failover-, Cross-Model-Fallback- und Stop-Aktionen.
• Weisen Sie einer Komponente die Verantwortung für das Retry-Budget zu.
• Erzwingen Sie eine End-to-End-Deadline und eine maximale Anzahl an Versuchen.
• Fügen Sie exponentielles Backoff mit Jitter für vorübergehende Fehler hinzu.
• Ordnen Sie Circuit Breaker dem kleinstmöglichen sinnvollen Fehlerbereich zu.
• Definieren Sie einen versionierten Fähigkeits-Contract für jeden Route-Alias.
• Blockieren Sie das automatische Umschalten, nachdem teilweise Ausgabe begonnen hat.
• Fügen Sie Idempotenz und Reconciliation für Write-side-Tools hinzu.
• Erfassen Sie Route-Gründe und finale Task-Ergebnisse.
• Injizieren Sie Transport-, Überlast-, Contract-, Streaming- und Side-Effect-Fehler.
• Führen Sie ein Canary für gleichwertiges Failover ein, bevor Sie Cross-Model-Fallback aktivieren.
• Fügen Sie Kill Switches für jedes Ziel und jede Fallback-Richtlinie hinzu.

FAQ

What is fallback routing for LLM APIs?

Fallback routing für LLM-APIs ist eine Zuverlässigkeitsrichtlinie, die ein anderes zulässiges Modell oder einen anderen Provider auswählt, wenn die bevorzugte Route eine Anfrage nicht abschließen kann. Sicheres Fallback prüft Replay-Safety, Kompatibilität der Fähigkeiten, Circuit-Health, Latenzbudget und Ausgabezustand, bevor umgeschaltet wird.

What is the difference between an LLM retry and fallback?

Ein Retry wiederholt die Anfrage gegen dasselbe Ziel. Failover wechselt zu einer gleichwertigen Infrastruktur, während der logische Modellvertrag erhalten bleibt. Cross-Model-Fallback ändert das Modell und erfordert daher stärkere Kompatibilitäts- und Qualitätstests.

Should an LLM API retry every 429 or 5xx error?

Nein. Retries sollten durch ein End-to-End-Deadline, ein Versuchslimit, eine Backoff-Richtlinie, den Schaltkreiszustand und eine Replay-Safety-Prüfung begrenzt werden. Ein gleichwertiges Failover kann besser sein, als wiederholt ein ungesundes Ziel anzurufen.

Can an LLM router switch models during a stream?

Nicht transparent, nachdem Ausgaben den Client erreicht haben. Der sichere Standard ist, den Stream klar fehlschlagen zu lassen oder einen neuen Turn auf Anwendungsebene zu starten. Das Verketten von Teilausgaben verschiedener Modelle kann den Antwortvertrag beschädigen.

When should cross-model fallback be disabled?

Deaktivieren Sie es, wenn das alternative Modell die erforderlichen Tools, strukturierten Ausgaben, Kontextgrenzen, Sicherheitsverhalten, Qualitäts-Schwellenwerte oder Zusicherungen zu Seiteneffekten nicht einhalten kann. Deaktivieren Sie außerdem das automatische Replay nach Teilausgaben oder unsicherer Tool-Ausführung.

How many fallback attempts should an LLM request make?

Es gibt keine universelle Zahl. Verwenden Sie die kleinstmögliche begrenzte Anzahl an Versuchen, die zum Latenzbudget und den Testnachweisen des Produkts passt. Der Router sollte stoppen, wenn die verbleibende Deadline keinen weiteren sinnvollen Versuch mehr zulässt.

Zuverlässiges Fallback bedeutet nicht „alles versuchen“. Es bedeutet, die nächste Aktion explizit, kompatibel, replay-sicher, beobachtbar und leicht stoppbar zu machen.