Repli automatique

provider.fallback liste les modèles de secours à essayer, dans l’ordre, lorsque le modèle principal échoue en amont.

Configuration

fallback attend un tableau d’identifiants de modèles et se place au même niveau que type, sous provider. 3 modèles au maximum ; au-delà, la requête renvoie 400.

cURL

Terminal


curl https://api.ofox.io/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)

Avec les SDK OpenAI officiels, extra_body doit être présent comme clé littérale dans le corps de la requête. Le SDK TypeScript l’envoie tel qu’il est écrit dans l’objet de paramètres. L’argument extra_body= du SDK Python fusionne son contenu à la racine du corps : la clé doit donc être imbriquée un niveau plus profond, ou transmise via un en-tête.

Ce qui déclenche un repli

Le repli ne couvre que les échecs survenant après que le routage a choisi un canal :

Situation	Comportement
Le fournisseur en amont renvoie une erreur	Repli — les modèles listés sont essayés dans l’ordre et la première réussite est renvoyée
Le routage lui-même échoue (modèle inexistant, ou fournisseur épinglé qui ne sert pas ce modèle)	Pas de repli — la requête se termine immédiatement

La seconde ligne mérite d’être dite clairement : épingler provider.type sur un fournisseur qui ne sert pas le modèle renvoie 400 provider_type_unavailable, et nommer un modèle inexistant renvoie 404 model_not_found. Ni l’un ni l’autre n’atteint la liste de repli. Les erreurs amont qui déclenchent effectivement un repli suivent le comportement de la passerelle, et non une liste figée.

Combinaison avec un fournisseur épinglé

fallback et type peuvent être envoyés ensemble : type contraint le fournisseur du modèle principal, fallback prend le relais si celui-ci échoue :


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

Référence complète des champs dans Routage des fournisseurs.

Erreurs courantes

`error.type`	Condition de déclenchement
`invalid_request_error`	La liste `fallback` contient plus de 3 modèles.

Bonnes pratiques

Choisir des modèles de secours de capacité comparable — pour que la qualité reste constante après un repli.
Varier les éditeurs — les modèles d’un même éditeur deviennent souvent indisponibles ensemble.
Surveiller la fréquence des replis — des replis fréquents indiquent qu’il faut changer de modèle principal.