Fallback

provider.fallback lista os modelos reserva a serem tentados, em ordem, quando o modelo principal falha no upstream.

Configuração

fallback recebe um array de IDs de modelo e fica no mesmo nível de type, sob provider. No máximo 3 modelos; acima disso a requisição retorna 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)

Com os SDKs oficiais da OpenAI, extra_body precisa existir como chave literal no corpo da requisição. O SDK de TypeScript envia exatamente como está escrito no objeto de parâmetros. O argumento extra_body= do SDK de Python mescla o conteúdo no nível superior do corpo, então a chave precisa ser aninhada um nível a mais, ou enviada como cabeçalho.

O que dispara um fallback

O fallback só cobre falhas que acontecem depois de o roteamento ter escolhido um canal:

Situação	Comportamento
O provedor upstream retorna um erro	Faz fallback — os modelos da lista são tentados em ordem e o primeiro sucesso é retornado
O próprio roteamento falha (o modelo não existe, ou o provedor fixado não o atende)	Sem fallback — a requisição termina imediatamente

A segunda linha vale dizer com clareza: fixar provider.type em um provedor que não atende o modelo retorna 400 provider_type_unavailable, e informar um modelo inexistente retorna 404 model_not_found. Nenhum dos dois chega à lista de fallback. Quais erros de upstream de fato disparam um fallback seguem o comportamento do gateway, não uma lista fixa.

Combinando com um provedor fixado

fallback e type podem ser enviados juntos: type restringe onde o modelo principal roda, e fallback cobre o que acontece se ele falhar:


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

Referência completa dos campos em Roteamento de provedores.

Erros comuns

`error.type`	Condição
`invalid_request_error`	A lista `fallback` tem mais de 3 modelos.

Boas práticas

Escolha reservas de capacidade parecida — para a qualidade se manter após o fallback.
Reservas de outro fabricante — modelos do mesmo fabricante costumam ficar indisponíveis juntos.
Acompanhe a frequência — fallbacks frequentes indicam que o modelo principal precisa ser trocado.