Estratégia de fallback de AI API: matriz de falhas de provedores

Retry de AI API, fallback de rota e substituição de modelo são ações diferentes. Retry repete uma tentativa sob o mesmo contrato. Fallback envia o modelo e o protocolo solicitados para outra rota elegível. Model Substitution altera o modelo e pode mudar qualidade, preço, latência, comportamento de Tools, Context Limits e formato de saída.

Uma policy confiável define as ações permitidas antes do incidente. A decisão considera Failure Class, fase da resposta, Idempotency da operação completa e quantas tentativas ainda cabem no deadline do usuário.

Separar retry, fallback e substituição de modelo

Use nomes diferentes em configuração, logs e runbooks.

Ação	O que muda	Uso adequado	Risco principal
Same-route retry	Tempo e Attempt Number	Recuperar falha transitória curta na mesma rota	Repetir carga contra dependência não saudável
Same-contract fallback	Upstream Channel, Account ou Group ordenado	Preservar modelo e protocolo quando um caminho falha	Incompatibilidade oculta entre rotas consideradas equivalentes
Model substitution	Model ID ou Model Policy nomeada	Compromisso de qualidade, custo ou disponibilidade aprovado pelo produto	Alteração silenciosa de comportamento e Billing

Não chame as três ações de “retry”. Operações precisa saber se a request foi repetida, movida para outro caminho ou respondida por outro modelo. Para o usuário, Model Substitution deve ser um Product Contract explícito, não um atalho invisível de recuperação.

Alguns gateways oferecem etapas ordenadas por Provider ou Model. A documentação de fallback da Cloudflare identifica, por exemplo, a etapa que produziu sucesso. A lição não é copiar uma policy específica, mas preservar Attempt-level Evidence sempre que a rota muda.

Aplicar quatro gates antes de repetir a request

Status Code sozinho não é Retry Policy. Avalie:

1. Failure Class: a falha é transitória, permanente, causada pelo caller ou ambígua?
2. Response Phase: ocorreu antes de Headers, antes de output efetivo ou depois de entregar output?
3. Idempotency: a operação completa pode ser repetida sem duplicar Side Effect?
4. Attempt Budget: ainda há Wall-clock Time e uma tentativa disponível?

A Retry Strategy do Google Cloud usa as mesmas distinções para APIs gerais: a resposta indica se repetir pode ajudar; Idempotency determina se é seguro. 408, 429, 5xx, Socket Timeout e Disconnect costumam ser transitórios, mas operações não idempotentes exigem condições mais fortes.

Em um AI Workflow, Idempotency vai além da request HTTP ao modelo. Repetir o Prompt pode propor novamente e-mail, reembolso, deploy ou Database Write. Cada Tool Execution precisa de Idempotency Key estável e resultado persistido, mesmo que a inferência seja Read-only.

Começar por uma Failure Matrix

Esta matriz é uma Application Policy conservadora. O gateway pode executar Same-contract Channel Failover interno antes de entregar o resultado terminal; coordene as duas camadas para não multiplicar tentativas.

Falha ou fase	Same-route retry	Same-contract fallback	Parar ou investigar	Motivo
Client Validation Error, Unsupported Field ou Malformed Request	Não	Não	Corrigir request	Repetir o mesmo contrato inválido não pode funcionar
Gateway Authentication, Authorization, Quota ou Policy Denial	Não	Não	Corrigir Account ou Policy	Outra Provider Route não deve contornar a decisão do gateway
Upstream Credential/Account Failure antes de output	Não na rota com falha	Sim, com Channel verificado	Isolar e investigar o Channel	O contrato permanece ao remover uma credential não saudável
Network Failure ou 408 antes de output	No máximo uma tentativa limitada se idempotente	Sim	Parar no deadline	Pode ser transitório, mas o resultado fica ambíguo após Disconnect
429 antes de output	Retry atrasado respeitando Retry-After	Sim, se outra rota equivalente tiver capacidade	Parar ao esgotar budget	Repetição imediata amplia Rate Limiting
500, 502, 503 ou 504 antes de output	Limitado com Backoff	Sim	Investigar falhas repetidas	Geralmente transitório, sem provar que todas as rotas são seguras
Provider Response inválida para o Schema antes do output downstream	Geralmente não	Apenas rota validada para o mesmo Schema	Isolar ou investigar Compatibility	Repetir implementação incompatível raramente ajuda
Model Refusal ou Completion segura pela Policy	Não	Não	Retornar resultado	Refusal válido não é falha de infraestrutura
Caller Cancellation ou downstream 499	Não	Não	Parar imediatamente	O caller não deseja mais o trabalho
Partial Stream após conteúdo visível ou Tool Arguments	Sem replay transparente	Sem fallback transparente	Marcar Partial e delegar à aplicação	Outro stream pode duplicar ou contradizer output entregue
Tool Side Effect com conclusão desconhecida	Não até Reconciliation	Não até Reconciliation	Consultar Idempotency Record ou sistema externo	Re-inference pode propor o mesmo efeito novamente

Um 503 antes de qualquer output é diferente de uma conexão encerrada após 400 tokens visíveis.

Tratar o início do stream como Commit Boundary

Antes do Downstream Output, o gateway pode descartar a tentativa com falha e escolher outra rota sem expor duas respostas. Depois do primeiro byte significativo, replay transparente deixa de ser seguro.

Reiniciar o stream pode:

• repetir o início da resposta;
• produzir continuação diferente;
• emitir Function Call duplicado com novo Call ID;
• alterar Usage e Cost sem fronteira clara;
• impedir o Client de identificar a tentativa de cada Event.

Se o stream quebrar depois do output, retorne erro Partial ou Transport com a Request Identity original. A aplicação pode oferecer “tentar novamente”, continuar de um checkpoint seguro ou descartar o output parcial. Não deve juntar um novo Model Stream ao anterior como se nada tivesse acontecido.

Para Function Calling, persista Tool Call Identities aceitas e Side-effect Results antes que um retry possa recriá-las. A comparação de Function Calling explica a relação entre Call IDs e Application Idempotency.

Limitar backoff por tentativas e tempo total

Exponential Backoff distribui as tentativas no tempo; Jitter evita que muitos clientes repitam ao mesmo tempo após falha compartilhada.

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

Respeite Retry-After válido quando couber no deadline. Backoff não concede permissão para retry: os gates de Failure e Idempotency precisam passar primeiro.

Defina Total Budget, não apenas um contador:

• máximo de tentativas por User Action;
• máximo de Elapsed Time incluindo Queue e Backoff;
• tentativas antes e depois de escolher Fallback Group;
• tempo mínimo restante para gerar resposta útil;
• propagação de Caller Cancellation para todas as tentativas ativas.

Para request interativa com deadline de 15 segundos, três tentativas de 10 segundos não formam uma policy executável. Batch Workload pode ter budget maior, mas também precisa de Terminal Deadline e Durable Job Identity.

Evitar Retry Amplification entre camadas

Se o SDK faz três tentativas, o gateway tenta três rotas por tentativa e o Upstream Proxy faz duas chamadas por rota:

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

Uma ação gera 18 Provider Calls. Durante incidentes isso aumenta Queueing, Rate Limits, custo e Recovery Time.

Distribua Retry Ownership:

• o gateway cuida do Same-contract Channel Failover imediato;
• a aplicação decide se a User Action completa pode ser repetida;
• SDK Automatic Retries são desativados ou limitados se o gateway já repete;
• Async Jobs usam um Durable Job ID e Attempt Ledger;
• nenhuma camada inicia tentativa após Caller Cancellation.

Registre o Attempt Number da camada e um End-to-end Request ID estável. Sem isso, cada componente parece ter feito apenas duas ou três tentativas enquanto a amplificação total fica oculta.

Verificar se o fallback preserva o contrato

O mesmo Model Name público não prova comportamento idêntico. Antes de incluir um Channel em fallback transparente, exija evidência:

Área do contrato	Evidência necessária
Model Identity	Requested Model disponível sem Silent Mapping
Endpoint	Request de Responses ou Chat Completions aceita como configurada
Streaming	Event Types, terminação, Usage e Cancellation funcionam
Structured Output	Subset necessário de JSON Schema e Strict Behavior funcionam
Function Calling	Tools, Call IDs, Argument Streaming e Results fazem Round-trip
Limits	Context, Output, Rate e Concurrency atendem ao Workload
Errors	Status e Error Bodies classificáveis sem expor Secrets
Usage and Cost	Tokens, Cache Fields, Service Tier e Price Policy definidos
Safety and Region	Policy, Data Path e Residency permanecem conformes

Se uma rota falhar em qualquer requisito, não é fallback transparente para esse workload. Ela pode ser usada sob Product Policy separada e explícita.

Mudar de modelo é sempre decisão de produto. Defina modelo permitido, Quality Floor, Price Ceiling, Tool Contract e User-visible Disclosure. Um erro de rota não justifica trocar silenciosamente para modelo mais barato ou fraco.

Entender o fallback atual da Modelflare

A Modelflare busca caminhos elegíveis para o modelo solicitado pelo API Client. Uma API Key regular possui Primary Group e pode ter Fallback Groups ordenados. Uma Smart API Key avalia Groups disponíveis conforme sua Routing Strategy. Nenhum mecanismo deve substituir silenciosamente o Requested Model.

Group-level RPM Admission ocorre antes de Billing e Upstream Request. Se o Group estiver cheio, outro Fallback Group ou Smart Routing Candidate pode ser avaliado; sem Group elegível, a resposta é 429.

Dentro do Group, Channel Priority define a ordem de Account Failover. Após Upstream Error, o Channel com falha é excluído e a seleção continua. O Channel Failover atual independe de RetryTimes e AutomaticRetryStatusCodes; termina no sucesso, esgotamento de rotas, Caller Cancellation ou quando o Downstream Output já começou.

Essas decisões internas de caminho same-model não autorizam um loop ilimitado no Client. Consulte Reliable AI API Routing para Groups e Channels e AI API Error Troubleshooting para distinguir Gateway Policy Error de Upstream Failure.

Preservar evidência de cada tentativa

Um 200 final não prova sucesso da primeira rota. O Channel ID final também não descreve tentativas anteriores. Preserve pelo menos:

• Request ID estável e Correlation ID visível ao caller;
• Attempt Sequence e referências de Group/Channel;
• Model e Endpoint Contract por tentativa;
• Failure Status, Error Class e Stream Phase;
• se Downstream Output havia começado;
• Timing Milestones e Cancellation State;
• Input, Output e Cached-token Usage disponíveis;
• Cost Attribution por tentativa concluída ou billable;
• Terminal Reason: Success, Exhausted, Cancelled, Partial ou Policy Stop.

Não armazene API Keys, Raw Prompts, Raw Responses ou Provider Credentials apenas para diagnóstico de fallback. Error Classes redigidas e Timing Metadata costumam bastar; Request Archives devem ser restritos, curtos e explicitamente habilitados.

Ensaiar a policy antes de produção

Use a Protocol Boundary real e inputs seguros e determinísticos:

1. desabilite o Primary Channel antes de Headers e verifique a próxima rota same-model;
2. retorne Rate Limit e valide Attempt Limits e Retry-After;
3. cancele o caller e prove que nenhuma tentativa posterior inicia;
4. interrompa o stream após output e impeça replay transparente;
5. envie Invalid Request e confirme que fallback não a esconde;
6. repita Tool Workflow e confirme apenas um Side Effect;
7. esgote todas as rotas e verifique um Terminal Error claro;
8. examine o Attempt Ledger e reconcilie Usage e Cost.

Implemente primeiro em um workload pequeno. Monitore Attempt Count, Success-after-fallback e Raw Success Rate separadamente e mantenha um caminho rápido para remover rotas não saudáveis. O objetivo não é maximizar fallback, mas recuperar com segurança dentro de deadline limitado, preservando o contrato do modelo e evidência para cada tentativa.