AI-API-Fallback-Strategie: Provider-Failure-Matrix erstellen

Ein Retry einer AI API, ein Route Fallback und eine Model Substitution sind drei verschiedene Aktionen. Ein Retry wiederholt einen Versuch unter demselben Vertrag. Ein Fallback sendet das angeforderte Modell und Protokoll an einen anderen geeigneten Pfad. Eine Model Substitution ändert das Modell und damit möglicherweise Qualität, Preis, Latenz, Tool-Verhalten, Context Limits und Ausgabeformat.

Eine belastbare Policy entscheidet bereits vor einem Incident, welche Aktion erlaubt ist. Maßgeblich sind Failure Class, Response Phase, Idempotency der gesamten Operation und die Zahl der Versuche, die noch in die Deadline des Nutzers passen.

Retry, Fallback und Model Substitution trennen

Verwenden Sie in Konfiguration, Logs und Runbooks eindeutige Begriffe.

Aktion	Was sich ändert	Geeigneter Zweck	Hauptrisiko
Same-route Retry	Zeit und Attempt Number	Kurzen transienten Fehler derselben Route überbrücken	Zusätzliche Last auf einer kranken Dependency
Same-contract Fallback	Upstream Channel, Account oder geordnete Group	Modell und Protokoll trotz ausgefallenem Pfad erhalten	Verdeckte Unterschiede angeblich äquivalenter Routen
Model Substitution	Model ID oder benannte Model Policy	Produktseitig genehmigter Trade-off bei Qualität, Kosten oder Verfügbarkeit	Stille Änderung von Verhalten und Billing

Bezeichnen Sie nicht alle drei Aktionen als „Retry“. Operations muss erkennen, ob ein Request wiederholt, verschoben oder von einem anderen Modell beantwortet wurde. Für Nutzer muss eine Model Substitution ein expliziter Product Contract sein, kein unsichtbarer Recovery Shortcut.

Manche Gateways unterstützen geordnete Provider- oder Model-Steps. Die Fallback-Dokumentation von Cloudflare weist etwa den erfolgreichen Step aus. Entscheidend ist nicht die konkrete Vendor Policy, sondern Attempt-level Evidence bei jedem Route-Wechsel.

Vor einem Replay vier Gates prüfen

Ein Status Code allein ist keine Retry Policy. Prüfen Sie:

1. Failure Class: Ist der Fehler transient, permanent, caller-bedingt oder im Ergebnis mehrdeutig?
2. Response Phase: Trat er vor Headers, vor wirksamem Output oder nach ausgeliefertem Output auf?
3. Idempotency: Kann die vollständige Operation ohne doppelten Side Effect wiederholt werden?
4. Attempt Budget: Bleiben genügend Wall-clock Time und ein freier Attempt?

Die Retry Strategy von Google Cloud trifft dieselben Grundunterscheidungen für allgemeine APIs: Die Response zeigt, ob ein Retry sinnvoll sein kann; Idempotency entscheidet, ob er sicher ist. 408, 429, 5xx, Socket Timeouts und Disconnects sind häufig transient, für nicht idempotente Operationen gelten jedoch strengere Bedingungen.

In einem AI Workflow endet Idempotency nicht am HTTP Request zum Modell. Ein wiederholter Prompt kann dieselbe E-Mail, Erstattung, Deployment-Aktion oder Datenbankänderung erneut vorschlagen. Tool Execution benötigt deshalb einen stabilen Idempotency Key und ein persistiertes Ergebnis, selbst wenn die Inference selbst Read-only ist.

Mit einer Failure Matrix beginnen

Die folgende Matrix ist eine konservative Application Policy. Da das Gateway vor dem terminalen Ergebnis bereits intern einen Same-contract Channel Failover ausführen kann, müssen beide Ebenen koordiniert werden.

Fehler oder Phase	Same-route Retry	Same-contract Fallback	Stoppen oder untersuchen	Begründung
Client Validation Error, Unsupported Field oder Malformed Request	Nein	Nein	Request korrigieren	Derselbe ungültige Vertrag kann nicht erfolgreich werden
Gateway Authentication, Authorization, Quota oder Policy Denial	Nein	Nein	Account oder Policy korrigieren	Eine Provider Route darf die Gateway-Entscheidung nicht umgehen
Upstream Credential/Account Failure vor Output	Nicht auf der fehlerhaften Route	Ja, mit verifiziertem Channel	Channel isolieren und untersuchen	Der User Contract bleibt beim Entfernen einer kranken Credential gleich
Network Failure oder 408 vor Output	Höchstens ein begrenzter Attempt bei Idempotency	Ja	An Deadline stoppen	Transient, aber nach Disconnect kann der Abschluss unklar sein
429 vor Output	Verzögert und mit Retry-After	Ja, wenn eine gleiche Route Kapazität hat	Bei ausgeschöpftem Budget stoppen	Sofortige Wiederholung verstärkt Rate Limiting
500, 502, 503 oder 504 vor Output	Begrenzt mit Backoff	Ja	Wiederholte Route-Fehler untersuchen	Meist transient, aber kein Beweis für jede andere Route
Schema-invalid Provider Response vor Downstream Output	Meist nein	Nur zu einer für dasselbe Schema geprüften Route	Compatibility untersuchen	Eine inkompatible Implementierung wird durch Wiederholung selten korrekt
Model Refusal oder Policy-safe Completion	Nein	Nein	Ergebnis zurückgeben	Ein gültiger Refusal ist kein Infrastrukturfehler
Caller Cancellation oder Downstream 499	Nein	Nein	Sofort stoppen	Der Caller benötigt die Arbeit nicht mehr
Partial Stream nach sichtbarem Content oder Tool Arguments	Kein transparenter Replay	Kein transparenter Fallback	Partial markieren, Application entscheidet	Ein neuer Stream kann Output duplizieren oder widersprechen
Tool Side Effect mit unbekanntem Abschluss	Erst nach Reconciliation	Erst nach Reconciliation	Idempotency Record oder Zielsystem abfragen	Re-Inference kann denselben Side Effect erneut auslösen

Ein 503 vor jedem Output ist nicht dasselbe wie ein Verbindungsabbruch nach 400 sichtbaren Tokens.

Stream-Beginn als Commit Boundary behandeln

Vor Downstream Output kann ein Gateway den fehlgeschlagenen Attempt verwerfen und eine andere Route wählen, ohne zwei Antworten auszuliefern. Nach dem ersten inhaltlich relevanten Byte ist transparenter Replay unsicher.

Ein neu gestarteter Stream kann:

• den Anfang wiederholen;
• eine andere Fortsetzung erzeugen;
• einen doppelten Function Call mit neuer Call ID senden;
• Usage und Kosten ohne klare Grenze verändern;
• Events für den Client unzuordenbar machen.

Bricht der Stream nach Output-Beginn, geben Sie einen terminalen Partial- oder Transport Error mit der ursprünglichen Request Identity zurück. Die Application kann einen expliziten neuen Versuch anbieten, an einem sicheren Checkpoint fortsetzen oder den Partial Output verwerfen. Sie sollte keinen neuen Model Stream unsichtbar an den alten anhängen.

Für Function Calling gilt eine noch strengere Grenze: Akzeptierte Tool Call Identities und Side-effect Results müssen persistiert sein, bevor ein Retry sie neu erzeugen kann. Der Function-Calling-Vergleich verbindet Call IDs mit Application Idempotency.

Backoff über Attempts und Wall-clock Time begrenzen

Exponential Backoff verteilt Versuche über die Zeit; Jitter verhindert synchrone Retries vieler Clients nach einem gemeinsamen Ausfall.

delay_cap = min(max_delay, base_delay * 2^retry_index)
sleep_for = random_between(0, delay_cap)

Ein gültiges Retry-After sollte beachtet werden, sofern es in die User Deadline passt. Backoff erteilt keine Retry-Erlaubnis: Failure- und Idempotency-Gates müssen zuerst erfüllt sein.

Definieren Sie ein Total Budget statt nur eines Counters:

• maximale Attempts pro User Action;
• maximale Elapsed Time inklusive Queue und Backoff;
• Attempts vor und nach der Auswahl einer Fallback Group;
• Restzeit, die für eine nützliche Antwort erforderlich ist;
• Propagation einer Caller Cancellation zu jedem aktiven Attempt.

Bei einer interaktiven Deadline von 15 Sekunden sind drei Attempts mit je 10 Sekunden keine ausführbare Policy. Batch Workloads dürfen länger laufen, benötigen aber ebenfalls Terminal Deadline und Durable Job Identity.

Retry Amplification über Ebenen verhindern

Wenn das SDK dreimal versucht, das Gateway pro Client Attempt drei Routen nutzt und ein Upstream Proxy jede Route zweimal aufruft, gilt:

3 client attempts × 3 gateway attempts × 2 upstream attempts = 18 provider calls

Eine User Action erzeugt 18 Provider Calls. Während eines Ausfalls steigen Queueing, Rate Limits, Kosten und Recovery Time.

Verteilen Sie Retry Ownership bewusst:

• Das Gateway besitzt den unmittelbaren Same-contract Channel Failover.
• Die Application entscheidet über die Wiederholung der vollständigen User Action.
• SDK Automatic Retries werden deaktiviert oder begrenzt, wenn das Gateway bereits versucht.
• Async Jobs nutzen eine Durable Job ID und ein Attempt Ledger.
• Nach Caller Cancellation startet keine Ebene einen neuen Attempt.

Loggen Sie den Attempt Number dieser Ebene und eine stabile End-to-end Request ID. Andernfalls sieht jede Komponente nur zwei oder drei Attempts, während die gesamte Verstärkung verborgen bleibt.

Vertragstreue eines Fallbacks nachweisen

Ein identischer öffentlicher Model Name beweist keine identische Route. Vor Aufnahme in ein transparentes Fallback Set sind folgende Nachweise nötig:

Vertragsbereich	Erforderliche Evidenz
Model Identity	Requested Model ohne Silent Mapping verfügbar
Endpoint	Konfigurierte Responses- oder Chat-Completions-Requests werden akzeptiert
Streaming	Event Types, Termination, Usage und Cancellation funktionieren
Structured Output	Benötigtes JSON-Schema-Subset und Strict Behavior funktionieren
Function Calling	Tools, Call IDs, Argument Streaming und Results funktionieren als Round-trip
Limits	Context, Output, Rate und Concurrency passen zum Workload
Errors	Status und Error Bodies sind ohne Secret-Leak klassifizierbar
Usage and Cost	Tokens, Cache Fields, Service Tier und Price Policy sind geklärt
Safety and Region	Policy, Data Path und Residency bleiben konform

Scheitert eine Route in einem Pflichtbereich, ist sie für diesen Workload kein transparenter Fallback. Unter einer separaten expliziten Product Policy kann sie dennoch verwendet werden.

Ein anderes Modell ist immer eine Produktentscheidung. Definieren Sie erlaubtes Modell, Quality Floor, Price Ceiling, Tool Contract und User-visible Disclosure. Ein Route Error rechtfertigt keinen stillen Wechsel auf ein billigeres oder schwächeres Modell.

Aktuelle Fallback-Semantik von Modelflare verstehen

Modelflare sucht geeignete Pfade für das vom API Client angeforderte Modell. Ein normaler API Key hat eine Primary Group und optional geordnete Fallback Groups. Ein Smart API Key bewertet verfügbare Groups anhand seiner Routing Strategy. Beide Mechanismen sollen das Requested Model nicht still ersetzen.

Group-level RPM Admission erfolgt vor Billing und Upstream Request. Ist die Group ausgelastet, kann eine geordnete Fallback Group oder ein Smart Routing Candidate geprüft werden; ohne geeignete Group folgt 429.

Innerhalb einer Group legt Channel Priority die Reihenfolge des Account Failovers fest. Nach einem Upstream Error wird der fehlerhafte Channel ausgeschlossen und die Auswahl fortgesetzt. Der aktuelle Channel Failover ist unabhängig von RetryTimes und AutomaticRetryStatusCodes; er stoppt bei Erfolg, erschöpften Routen, Caller Cancellation oder begonnenem Downstream Output.

Das sind interne Same-model Path Decisions und keine Erlaubnis für eine unbegrenzte Client-Schleife. Reliable AI API Routing behandelt Group- und Channel-Design; AI API Error Troubleshooting trennt Gateway Policy Errors von Upstream Failures.

Evidenz für jeden Attempt erhalten

Ein finales 200 beweist nicht, dass die erste Route erfolgreich war. Eine finale Channel ID beschreibt fehlgeschlagene Attempts nicht. Speichern Sie mindestens:

• stabile Request ID und Caller-visible Correlation ID;
• Attempt Sequence und Group/Channel Reference;
• Model und Endpoint Contract je Attempt;
• Failure Status, Error Class und Stream Phase;
• ob Downstream Output begonnen hatte;
• Timing Milestones und Cancellation State;
• verfügbare Input-, Output- und Cached-token Usage;
• Cost Attribution je abgeschlossenem oder billable Attempt;
• Terminal Reason: Success, Exhausted, Cancelled, Partial oder Policy Stop.

Speichern Sie nicht allein für Fallback-Diagnosen API Keys, Raw Prompts, Raw Responses oder Provider Credentials. Redacted Error Classes und Timing Metadata reichen meist aus; eingeschränkte kurzlebige Request Archives gehören nur in explizit aktivierte Untersuchungen.

Policy vor Production Traffic üben

Führen Sie mit echten Protocol Boundaries und sicheren deterministischen Inputs eine Staging Exercise durch:

1. Primary Channel vor Headers deaktivieren und nächste Same-model Route prüfen;
2. Rate Limit zurückgeben und Attempt Limits sowie Retry-After validieren;
3. Caller abbrechen und nachweisen, dass kein späterer Attempt beginnt;
4. Stream nach Output unterbrechen und transparenten Replay ausschließen;
5. ungültigen Request senden und prüfen, dass Fallback ihn nicht verdeckt;
6. Tool Workflow wiederholen und genau einen Side Effect nachweisen;
7. alle Routen erschöpfen und einen eindeutigen Terminal Error prüfen;
8. Attempt Ledger prüfen und Usage sowie Cost abgleichen.

Führen Sie die Policy zuerst für einen kleinen Workload ein. Beobachten Sie Attempt Count, Success-after-fallback und Raw Success Rate getrennt und halten Sie einen schnellen Weg bereit, kranke Routen zu entfernen. Das Ziel ist nicht möglichst häufiger Fallback, sondern sichere Recovery innerhalb einer begrenzten Deadline bei unverändertem Modellvertrag und vollständiger Attempt-Evidenz.