Stratégie de fallback AI API : matrice de défaillance fournisseur

Un retry d’AI API, un fallback de route et une substitution de modèle sont trois actions distinctes. Le retry répète un attempt sous le même contrat. Le fallback envoie le modèle et le protocole demandés vers une autre route éligible. La substitution change le modèle et peut modifier qualité, prix, latence, comportement des Tools, Context Limits et format de sortie.

Une policy fiable décide des actions autorisées avant l’incident. Elle tient compte de la Failure Class, de la phase de réponse, de l’Idempotency de l’opération complète et du nombre d’attempts encore compatibles avec la deadline utilisateur.

Distinguer retry, fallback et substitution de modèle

Employez des noms distincts dans la configuration, les logs et les runbooks.

Action	Ce qui change	Usage approprié	Risque principal
Same-route retry	Temps et Attempt Number	Absorber une défaillance transitoire courte sur la même route	Ajouter de la charge à une dépendance défaillante
Same-contract fallback	Upstream Channel, Account ou Group ordonné	Conserver modèle et protocole lorsqu’un chemin échoue	Incompatibilité cachée entre routes supposées équivalentes
Model substitution	Model ID ou Model Policy nommée	Compromis qualité, coût ou disponibilité validé par le produit	Changement silencieux de comportement et de facturation

Ne regroupez pas ces actions sous le mot « retry ». Les équipes d’exploitation doivent savoir si une requête a été rejouée, déplacée ou servie par un autre modèle. Pour l’utilisateur, la Model Substitution doit être un contrat explicite, pas un raccourci de récupération invisible.

Certains gateways acceptent des étapes ordonnées par Provider ou Model. La documentation Fallback de Cloudflare expose par exemple l’étape qui a réussi. La leçon utile n’est pas de copier une policy fournisseur, mais de conserver une Attempt-level Evidence dès qu’une route change.

Appliquer quatre gates avant tout replay

Un Status Code n’est pas une Retry Policy. Évaluez quatre gates :

1. Failure Class : erreur transitoire, permanente, imputable au caller ou ambiguë ?
2. Response Phase : avant les headers, avant l’output effectif ou après livraison ?
3. Idempotency : l’opération complète peut-elle être rejouée sans Side Effect en double ?
4. Attempt Budget : reste-t-il assez de Wall-clock Time et un attempt disponible ?

La Retry Strategy de Google Cloud pose les mêmes distinctions pour les APIs générales : la réponse indique si le retry peut être utile, et l’idempotence s’il est sûr. 408, 429, 5xx, Socket Timeout et Disconnect sont souvent transitoires, mais les opérations non idempotentes requièrent des conditions plus strictes.

Dans un AI Workflow, l’Idempotency dépasse la requête HTTP au modèle. Rejouer un Prompt peut reproposer le même e-mail, remboursement, déploiement ou Database Write. Chaque Tool Execution doit donc posséder une Idempotency Key stable et un résultat persisté, même si l’inférence est Read-only.

Partir d’une Failure Matrix

La matrice suivante est une Application Policy conservatrice. Le gateway peut avoir exécuté un Same-contract Channel Failover interne avant que l’application reçoive le résultat terminal ; coordonnez les deux couches.

Échec ou phase	Same-route retry	Same-contract fallback	Arrêt ou investigation	Raison
Client Validation Error, Unsupported Field ou Malformed Request	Non	Non	Corriger la requête	Rejouer le même contrat invalide ne peut réussir
Gateway Authentication, Authorization, Quota ou Policy Denial	Non	Non	Corriger Account ou Policy	Une Provider Route ne doit pas contourner la décision du gateway
Upstream Credential/Account Failure avant output	Non sur la route défaillante	Oui avec un Channel vérifié	Isoler et examiner le Channel	Le contrat reste inchangé en retirant une credential défaillante
Network Failure ou 408 avant output	Au plus un attempt borné si idempotent	Oui	Stop à la deadline	Transitoire, mais le résultat peut être ambigu après Disconnect
429 avant output	Retry différé avec Retry-After	Oui si une route équivalente a de la capacité	Stop au budget	Les retries immédiats amplifient le Rate Limit
500, 502, 503 ou 504 avant output	Borné avec Backoff	Oui	Examiner les échecs répétés	Souvent transitoire, sans garantir toutes les routes
Provider Response invalide pour le Schema avant output downstream	Généralement non	Seulement vers une route validée pour ce Schema	Isoler ou examiner la Compatibility	Répéter une implémentation incompatible aide rarement
Model Refusal ou Completion conforme à la Policy	Non	Non	Renvoyer le résultat	Un refus valide n’est pas une panne d’infrastructure
Caller Cancellation ou downstream 499	Non	Non	Stop immédiat	Le caller ne souhaite plus le travail
Partial Stream après contenu visible ou Tool Arguments	Pas de replay transparent	Pas de fallback transparent	Marquer Partial, décision applicative	Un second stream peut dupliquer ou contredire l’output
Tool Side Effect au statut final inconnu	Non avant Reconciliation	Non avant Reconciliation	Interroger l’Idempotency Record ou le système cible	La réinférence peut proposer le même effet

Un 503 avant tout output n’est pas équivalent à une connexion rompue après 400 tokens visibles.

Considérer le début du stream comme Commit Boundary

Avant le Downstream Output, le gateway peut écarter un attempt défaillant et choisir une autre route sans exposer deux réponses. Après le premier byte significatif, le replay transparent devient dangereux.

Redémarrer le stream peut :

• répéter le début de la réponse ;
• produire une continuation différente ;
• émettre un Function Call dupliqué avec un nouveau Call ID ;
• modifier Usage et Cost sans frontière claire ;
• empêcher le client d’associer les Events à leur attempt.

Si le stream se rompt après le début de l’output, retournez une erreur Partial ou Transport avec la Request Identity initiale. L’application peut proposer un « réessayer » explicite, reprendre depuis un checkpoint sûr ou écarter l’output partiel. Elle ne doit pas raccorder silencieusement un nouveau Model Stream à l’ancien.

Pour Function Calling, persistez les Tool Call Identities acceptées et leurs Side-effect Results avant qu’un retry puisse les recréer. La comparaison Function Calling relie Call IDs et Application Idempotency.

Borner le backoff par attempts et temps total

Exponential Backoff espace les attempts ; Jitter évite que tous les clients retentent simultanément après une panne commune.

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

Respectez un Retry-After valide s’il tient dans la deadline. Le backoff n’autorise pas le retry : les gates Failure et Idempotency doivent être franchis.

Définissez un Total Budget, pas seulement un compteur :

• maximum d’attempts par User Action ;
• Elapsed Time maximale, Queue et Backoff inclus ;
• attempts avant et après sélection d’un Fallback Group ;
• temps minimum pour produire une réponse utile ;
• propagation de la Caller Cancellation à tous les attempts actifs.

Pour une requête interactive avec 15 secondes de deadline, trois attempts de 10 secondes ne constituent pas une policy réalisable. Un Batch Workload peut disposer d’un budget supérieur, mais requiert aussi Terminal Deadline et Durable Job Identity.

Éviter la Retry Amplification entre couches

Si le SDK fait trois attempts, le gateway essaie trois routes pour chacun et un Upstream Proxy effectue deux appels par route :

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

Une seule action produit 18 Provider Calls. Pendant une panne, Queueing, Rate Limits, coûts et temps de reprise augmentent.

Attribuez clairement la Retry Ownership :

• le gateway gère le Same-contract Channel Failover immédiat ;
• l’application décide si la User Action complète peut être rejouée ;
• les SDK Automatic Retries sont désactivés ou bornés si le gateway réessaie déjà ;
• les Async Jobs utilisent un Durable Job ID et un Attempt Ledger ;
• aucune couche ne démarre un attempt après Caller Cancellation.

Loggez l’Attempt Number local et un End-to-end Request ID stable. Sinon, chaque couche semble n’avoir fait que deux ou trois tentatives alors que l’amplification globale reste invisible.

Prouver que le fallback préserve le contrat

Le même Model Name public ne garantit pas des routes équivalentes. Avant d’ajouter un Channel à un Fallback Set transparent, exigez :

Zone du contrat	Preuve requise
Model Identity	Requested Model disponible sans Silent Mapping
Endpoint	Requête Responses ou Chat Completions acceptée telle que configurée
Streaming	Event Types, terminaison, Usage et Cancellation fonctionnels
Structured Output	Sous-ensemble JSON Schema requis et Strict Behavior fonctionnels
Function Calling	Tools, Call IDs, Argument Streaming et Results en Round-trip
Limits	Context, Output, Rate et Concurrency adaptés au Workload
Errors	Status et Error Bodies classifiables sans fuite de Secret
Usage and Cost	Tokens, Cache Fields, Service Tier et Price Policy compris
Safety and Region	Policy, Data Path et Residency conformes

Si une route échoue sur un prérequis, elle n’est pas un fallback transparent pour ce workload. Elle peut rester utilisable sous une Product Policy séparée et explicite.

Changer de modèle est toujours une décision produit. Définissez modèle autorisé, Quality Floor, Price Ceiling, Tool Contract et User-visible Disclosure. Une route en erreur ne justifie pas le passage silencieux à un modèle moins cher ou plus faible.

Comprendre la sémantique actuelle de Modelflare

Modelflare recherche des chemins éligibles pour le modèle demandé par l’API Client. Une API Key standard possède un Primary Group et éventuellement des Fallback Groups ordonnés. Une Smart API Key évalue les Groups accessibles selon sa Routing Strategy. Aucun mécanisme ne doit remplacer silencieusement le Requested Model.

Le Group-level RPM Admission intervient avant Billing et Upstream Request. Si le Group sélectionné est plein, un Fallback Group ordonné ou un Smart Routing Candidate peut être évalué ; sans Group éligible, la réponse est 429.

Dans un Group, Channel Priority fixe l’ordre d’Account Failover. Après un Upstream Error, le Channel défaillant est exclu et la sélection continue. Le Channel Failover actuel est indépendant de RetryTimes et AutomaticRetryStatusCodes ; il s’arrête au succès, à l’épuisement des routes, à la Caller Cancellation ou après le début du Downstream Output.

Ces Same-model Path Decisions internes n’autorisent pas une boucle Client illimitée. Consultez Reliable AI API Routing pour les Groups et Channels, puis AI API Error Troubleshooting pour distinguer Gateway Policy Error et Upstream Failure.

Conserver les preuves de chaque attempt

Un 200 final ne prouve pas que la première route a réussi. Un Channel ID final ne décrit pas les attempts échoués. Conservez au minimum :

• Request ID stable et Correlation ID visible du caller ;
• Attempt Sequence et références Group/Channel ;
• Model et Endpoint Contract par attempt ;
• Failure Status, Error Class et Stream Phase ;
• état du Downstream Output ;
• Timing Milestones et Cancellation State ;
• Input, Output et Cached-token Usage disponibles ;
• Cost Attribution par attempt terminé ou billable ;
• Terminal Reason : Success, Exhausted, Cancelled, Partial ou Policy Stop.

Ne conservez pas API Keys, Raw Prompts, Raw Responses ou Provider Credentials uniquement pour diagnostiquer le fallback. Des Error Classes expurgées et des Timing Metadata suffisent généralement ; les Request Archives doivent être restreintes, temporaires et activées explicitement.

Tester la policy avant le trafic de production

Avec la vraie Protocol Boundary et des inputs sûrs et déterministes :

1. désactivez le Primary Channel avant headers et vérifiez la route same-model suivante ;
2. retournez un Rate Limit et contrôlez Attempt Limits et Retry-After ;
3. annulez le caller et prouvez qu’aucun nouvel attempt ne démarre ;
4. rompez le stream après output et excluez le replay transparent ;
5. envoyez une Invalid Request et prouvez que le fallback ne la masque pas ;
6. répétez un Tool Workflow et vérifiez un seul Side Effect ;
7. épuisez toutes les routes et vérifiez une Terminal Error claire ;
8. examinez l’Attempt Ledger et réconciliez Usage et Cost.

Déployez d’abord sur un petit workload. Surveillez séparément Attempt Count, Success-after-fallback et Raw Success Rate, avec un moyen rapide de retirer une route défaillante. L’objectif n’est pas de maximiser les fallbacks, mais de récupérer en sécurité dans une deadline bornée, sans changer le contrat du modèle et avec une preuve pour chaque attempt.