Fallbacks

Por Que Fallbacks São Importantes

Quedas de providers acontecem. OpenAI, Anthropic e Google todos experimentam downtime, rate limiting e desempenho degradado. Se sua aplicação depende de um único provider, uma única queda derruba você junto.

Fallbacks garantem que sua aplicação continue funcionando, roteando automaticamente para um provider alternativo quando o primário falha. Seus usuários nunca percebem a diferença.

Como Fallbacks Funcionam

Quando uma requisição falha, o gateway tenta o próximo provider na sua cadeia de fallback. Combinado com o circuit breaker, providers que já são conhecidos por estarem falhando são ignorados completamente — sem latência desperdiçada em requisições fadadas ao fracasso.

graph TD
    A[Incoming Request] --> B[Provider A]
    B -->|Success| C[Return Response]
    B -->|Failure| D{Circuit Breaker Open for B?}
    D -->|Yes| E[Skip — already failing]
    D -->|No| F[Record Failure]
    F --> E
    E --> G[Provider B]
    G -->|Success| C
    G -->|Failure| H{Circuit Breaker Open for C?}
    H -->|Yes| I[Skip]
    H -->|No| J[Record Failure]
    J --> I
    I --> K[Provider C]
    K -->|Success| C
    K -->|Failure| L[Return Error — all providers exhausted]

O gateway traduz o formato da requisição entre providers automaticamente. Uma requisição escrita para gpt-4o é adaptada para o formato correto quando faz fallback para claude-sonnet-4-6 ou gemini-2.5-pro.

Configurando Fallbacks

Existem duas formas de configurar fallbacks.

Via Regras de Roteamento

Crie uma regra de roteamento com fallback no dashboard em Routing > Rules. Defina uma lista ordenada por prioridade de pares provider/modelo. O gateway tenta cada um em ordem quando o provider de maior prioridade falha.

Essa abordagem é ideal quando você quer controle centralizado e a capacidade de alterar o comportamento de fallback sem fazer deploy de código.

Via String de Modelo

Passe uma lista separada por vírgulas de modelos no campo model da sua requisição:

"model": "gpt-4o,claude-sonnet-4-6,gemini-2.5-pro"

O gateway tenta cada modelo em ordem, da esquerda para a direita. Essa abordagem é a mais simples — nenhuma configuração no dashboard é necessária.

Exemplos de Código

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});

const response = await client.chat.completions.create({
  model: "gpt-4o,claude-sonnet-4-6,gemini-2.5-pro",
  messages: [{ role: "user", content: "Summarize the latest AI news." }],
});

console.log(response.choices[0].message.content);

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.floopy.ai/v1",
    api_key=os.environ["FLOOPY_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o,claude-sonnet-4-6,gemini-2.5-pro",
    messages=[{"role": "user", "content": "Summarize the latest AI news."}],
)

print(response.choices[0].message.content)

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o,claude-sonnet-4-6,gemini-2.5-pro",
    "messages": [{"role": "user", "content": "Summarize the latest AI news."}]
  }'

Integração com Circuit Breaker

O gateway rastreia a taxa de falha de cada provider usando uma janela deslizante. Quando a taxa de falha de um provider excede o limite configurado, seu circuito abre e o provider é ignorado automaticamente para requisições subsequentes. Isso evita desperdiçar latência e tokens em providers que estão sabidamente fora do ar.

Após um período de cooldown, o circuito entra em estado half-open e permite que uma única requisição de teste passe. Se a requisição de teste for bem-sucedida, o circuito fecha e o provider volta à rotação. Se falhar, o circuito permanece aberto por outro intervalo de cooldown.

Isso significa que cadeias de fallback respondem instantaneamente a quedas — as primeiras falhas acionam o circuito, e todas as requisições subsequentes ignoram o provider com falha sem latência adicional.

Detectando Fallbacks

Quando um provider de fallback atende sua requisição, a resposta inclui headers adicionais:

Use esses headers para registrar qual provider atendeu cada requisição e para monitorar sua taxa de fallback ao longo do tempo.

Boas Práticas

• Ordene por preferência. Coloque seu provider mais rápido ou mais barato primeiro. Fallbacks são tentados da esquerda para a direita, então o provider primário lida com a maior parte do tráfego em condições normais.
• Misture famílias de providers. Usar gpt-4o,claude-sonnet-4-6,gemini-2.5-pro dá a você verdadeira redundância entre OpenAI, Anthropic e Google. Se você listar três modelos da OpenAI, uma queda geral da plataforma OpenAI derruba toda a sua cadeia.
• Monitore a taxa de fallback. Uma taxa de fallback crescente no dashboard é um sinal precoce de que seu provider primário está degradado, mesmo antes de uma queda completa. Configure alertas para detectar isso.
• Teste sua cadeia. Verifique se seus modelos de fallback produzem qualidade de saída aceitável para o seu caso de uso. Um fallback que retorna resultados ruins é pior do que um erro claro em muitas aplicações.
• Combine com cache. Respostas cacheadas são retornadas antes da cadeia de fallback ser avaliada. Altas taxas de cache hit reduzem sua exposição a falhas de providers.