Toda API de LLM tem seus minutos ruins: um 503, um timeout, uma rajada de 429. Fallback significa que esses minutos não viram uma queda no seu app. Este post mostra como fazer failover entre provedores compatíveis com a OpenAI no seu próprio código. Ele cobre quais erros devem acioná-lo, como um circuit breaker o mantém rápido e o que precisa bater entre os provedores para os usuários não perceberem a troca.
Antes de tudo: a BroadNet Inference não roteia nem faz failover entre provedores por você, e o BroadRouter também não. O BroadRouter é o site da própria BroadNet, não um roteador. Você monta o fallback, seja no seu client, como mostrado abaixo, seja num gateway como o LiteLLM.
Por que manter um provedor de fallback?
Porque a maioria das APIs self-service não promete nada sobre uptime. Os termos da BroadNet dizem isso com todas as letras na seção 7.4: “self-serve has no availability commitment” (tradução: o self-service não tem compromisso de disponibilidade), e níveis de serviço só existem num acordo escrito separado (verificado em 15 de novembro de 2026). A comparação de SLAs de APIs de LLM mostra com o que outros provedores se comprometem. Se a sua funcionalidade precisa ficar no ar, um segundo provedor é o seguro prático, diga o SLA o que disser.
Limites de taxa são o segundo motivo. Uma chave de pagamento por uso da BroadNet permite 30 requisições por minuto e 4 em andamento. Um pico de tráfego acima disso devolve 429, e um segundo provedor pode absorver o excesso enquanto você aumenta a capacidade.
Quais erros devem acionar um failover?
Divida os erros em dois grupos. Alguns são culpa do provedor e podem dar certo em outro lugar. Outros são culpa sua e vão falhar em qualquer lugar.
| Erro | Failover? | Por quê |
|---|---|---|
| Erro de conexão, timeout | Sim, depois das novas tentativas | O provedor ou a rede está inacessível |
| 500, 502, 503, 504 | Sim, depois das novas tentativas | A documentação da BroadNet diz para primeiro “retry with bounded exponential backoff” (tradução: tentar de novo com backoff exponencial limitado) |
| 429, limite de taxa ou de concorrência | Sim, depois do backoff | Falta capacidade neste provedor, a requisição não está errada |
| 429, limite de gasto | Não | O failover contorna o orçamento que você definiu de propósito |
| 400, 422 | Não | A requisição é inválida e vai falhar no próximo provedor também |
| 401, 402 | Não | Chave, franquia ou saldo. Na BroadNet, um 401 também cobre uma franquia de pagamento por uso esgotada, então o failover esconde um problema de cobrança |
| 403, 413 | Não | Política ou tamanho; corrija a requisição |
A referência da API da BroadNet diz que um 429 significa “a rate, concurrency, token-rate or spending limit was reached” (tradução: foi atingido um limite de taxa, de concorrência, de tokens por segundo ou de gasto) e recomenda “use response details and bounded backoff” (tradução: usar os detalhes da resposta e um backoff limitado). Leia esses detalhes antes do failover, para que um 429 por limite de gasto pare a requisição em vez de movê-la. O guia de códigos de erro lista todos os status.
Tente de novo antes do failover. O SDK Python da OpenAI já repete erros de conexão, 408, 409, 429 e respostas 5xx “2 times by default, with a short exponential backoff” (tradução: 2 vezes por padrão, com um backoff exponencial curto), e o timeout padrão dele é de 10 minutos (README, verificado em 15 de novembro de 2026). Dez minutos é tempo demais para esperar antes de um failover. Defina timeout por client. O post sobre como tratar 429 explica backoff com jitter.
Como fica um failover em Python?
Dois clients, uma lista ordenada e um pequeno circuit breaker. O principal é o GLM 5.3 na BroadNet. O reserva é o mesmo modelo aberto na DeepInfra, cuja documentação informa a base URL https://api.deepinfra.com/v1/openai (verificado em 15 de novembro de 2026).
import os
import time
from openai import (OpenAI, APIConnectionError, APITimeoutError,
RateLimitError, InternalServerError)
PROVIDERS = [
{"name": "broadnet", "model": "broadnet/glm-5.3",
"client": OpenAI(base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
max_retries=2, timeout=60)},
{"name": "deepinfra", "model": "zai-org/GLM-5.3",
"client": OpenAI(base_url="https://api.deepinfra.com/v1/openai",
api_key=os.environ["DEEPINFRA_API_KEY"],
max_retries=2, timeout=60)},
]
# Provider-side failures only. 400, 401, 402, 403 and 422 raise straight through.
FAILOVER_ON = (APIConnectionError, APITimeoutError, RateLimitError, InternalServerError)
TRIP_AFTER = 3 # consecutive failures before the breaker opens
COOLDOWN = 30 # seconds to skip a provider once its breaker is open
state = {p["name"]: {"fails": 0, "open_until": 0.0} for p in PROVIDERS}
def chat(messages, **kwargs):
last_error = None
for p in PROVIDERS:
s = state[p["name"]]
if time.monotonic() < s["open_until"]:
continue # breaker open: don't wait on a provider that is down
try:
reply = p["client"].chat.completions.create(
model=p["model"], messages=messages, **kwargs)
s["fails"] = 0
return p["name"], reply
except FAILOVER_ON as err:
last_error = err
s["fails"] += 1
if s["fails"] >= TRIP_AFTER:
s["open_until"] = time.monotonic() + COOLDOWN
raise RuntimeError("every provider failed") from last_error
served_by, reply = chat([{"role": "user", "content": "Reply with one short sentence."}],
max_tokens=1000)
print(served_by, reply.model, reply.choices[0].message.content)
Quatro detalhes importam:
- Classes de exceção. O SDK lança
RateLimitErrorpara 429,InternalServerErrorpara 500 ou mais, eAPIConnectionError(comAPITimeoutErrorcomo subclasse) quando não consegue conectar. Todo o resto fica sem captura de propósito. Para deixar de fora os 429 de limite de gasto, inspecioneerr.responseantes de continuar. - O circuit breaker. Sem ele, cada requisição paga o timeout inteiro num principal morto antes de seguir. Depois de três falhas seguidas, o principal é pulado por 30 segundos. Depois disso, a próxima requisição testa ele de novo.
- Registre quem atendeu. Devolva o nome do provedor e guarde
reply.model. Quando a qualidade mudar, você precisa saber qual provedor respondeu. - Orçamento de raciocínio. O GLM 5.3 raciocina antes de responder. A documentação da BroadNet diz que o raciocínio conta em
max_tokens, então deixe 1.000 ou mais em todos os provedores.
Como mapear IDs de modelo entre provedores?
O mesmo modelo aberto tem um ID diferente em cada host, e os recursos que cada host lista podem variar. O GLM 5.3 em 15 de novembro de 2026:
| BroadNet Inference | DeepInfra | Fireworks AI | |
|---|---|---|---|
| ID do modelo | broadnet/glm-5.3 |
zai-org/GLM-5.3 |
accounts/fireworks/models/glm-5p3 |
| Contexto | 1.048.576 tokens | 1.048.576 tokens | “1040k” tokens |
| Ferramentas | Documentadas | “Function” listado | Suportadas |
| Saída estruturada | Documentada | “JSON” listado | Não verificado |
Daí saem duas regras. Primeiro, mantenha o mapeamento na configuração, não espalhado pelo código. Segundo, escolha o fallback de acordo com o que as suas requisições usam. Na BroadNet, ferramentas e saída estruturada estão documentadas só para o GLM 5.3 e o Qwen3.8 27B. Um agente com chamada de ferramentas pode passar do GLM 5.3 para o GLM 5.3 em outro lugar. Ele não pode passar com segurança para um modelo que não documenta ferramentas. Se o reserva tiver uma janela de contexto menor, corte o prompt ou pule esse reserva nas requisições longas. As base URLs de 14 provedores estão na referência de base URLs.
Como manter respostas comparáveis depois da troca?
Os mesmos pesos em dois hosts ainda podem responder diferente, porque os hosts podem servir precisões, chat templates ou parâmetros padrão diferentes. Um modelo diferente com certeza responde diferente.
- Rode o seu conjunto de avaliação contra cada item da lista, não só contra o principal.
- Fixe
temperature,max_tokense o prompt de sistema em cada requisição, para que os padrões do provedor não mudem a saída. - Valide a saída estruturada do mesmo jeito em todos os caminhos. Como corrigir JSON inválido cobre o loop de reparo e nova tentativa.
- Prefira o mesmo modelo em outro lugar a um modelo diferente no mesmo host. Os usuários notam uma mudança de estilo mais que alguns segundos de latência.
E o streaming e as chamadas de ferramenta?
Um stream pode falhar no meio. A documentação da BroadNet diz que um stream que termina antes de data: [DONE] deve ser tratado como incompleto: registre o X-Request-ID e decida se a sua aplicação pode enviar uma nova requisição com segurança.
- Antes do primeiro token: faça failover à vontade. O usuário não viu nada.
- Depois que os tokens apareceram: recomece no reserva e substitua a resposta parcial, ou mostre um erro com um botão de tentar de novo. Emendar meias respostas de dois provedores fica ruim de ler.
- Chamadas de ferramenta com efeitos colaterais: nunca execute de novo um passo que envia um e-mail, cobra um cartão ou grava num banco de dados só porque a chamada ao modelo falhou. Dê a cada ação uma chave de idempotência. Agentes de longa duração trata de checkpoints.
Streaming com SSE explica como detectar um stream que terminou antes da hora.
Quanto custa o failover?
- Trabalho duplicado. Um timeout do seu lado não prova que o provedor parou. Na cobrança por token, cada nova tentativa é uma nova inferência, então espere pagar duas vezes por algumas requisições.
- Preços diferentes. O reserva cobra pelas próprias tarifas. Em 15 de novembro de 2026 a DeepInfra listava um preço promocional para o GLM-5.3, então confira de novo antes de fazer o orçamento. A BroadNet cobra $0.78 de entrada, $0.173 de entrada em cache e $3.46 de saída por 1M de tokens.
- Cache frio. A entrada em cache não passa de um provedor para outro. As primeiras requisições no reserva pagam preço cheio de entrada por um prefixo que estava em cache no principal. Veja tokens de entrada em cache.
- Hedging. Mandar cada requisição para dois provedores ao mesmo tempo e ficar com a primeira resposta reduz a latência de cauda, mas praticamente dobra a conta. Use só onde a latência vale isso.
O fallback atende aos mesmos termos de dados?
Um provedor de fallback é outro operador que recebe os mesmos prompts. Se você prometeu algo aos clientes sobre os dados deles, a promessa precisa valer para cada item da lista.
A declaração de privacidade da BroadNet diz: “We do not retain prompts, audio, images, answers or transcripts” (tradução: não retemos prompts, áudio, imagens, respostas ou transcrições). O conteúdo de inferência não é retido; os metadados necessários de conta, cobrança e segurança são mantidos conforme descrito nessa declaração. Ela também diz que dados de inferência não são usados para treinar, fazer fine-tuning ou avaliar modelos. A declaração diz que os modelos hospedados “run on BroadNet-owned or leased hardware in the United States, with partner capacity as backup” (tradução: rodam em hardware próprio ou alugado da BroadNet nos Estados Unidos, com capacidade de parceiros como reserva); o DeepSeek V4.1 Flash é hospedado por parceiro. Para dados com requisitos de residência, os termos (seção 7.3a) dizem para combinar os locais de processamento antes de enviá-los. Confira os mesmos pontos no reserva: retenção, uso para treinamento, local e suboperadores. Se ele não atender, deixe as requisições sensíveis fora do caminho de fallback e faça-as falhar de forma fechada. O checklist de retenção zero de dados lista as perguntas.
Vale usar um gateway como o LiteLLM?
Use um gateway se vários serviços precisam das mesmas regras de fallback. O proxy do LiteLLM aceita uma lista fallbacks testada em ordem. num_retries repete um grupo de modelos antes de cair no fallback. allowed_fails e cooldown_time tiram por um tempo um deployment que está falhando, o que funciona como circuit breaker. context_window_fallbacks e content_policy_fallbacks, separados, cuidam desses tipos de erro (documentação do LiteLLM, verificado em 15 de novembro de 2026):
model_list:
- model_name: glm
litellm_params:
model: openai/broadnet/glm-5.3
api_base: https://inference.broadnet.ai/v1
api_key: os.environ/BROADNET_API_KEY
- model_name: glm-backup
litellm_params:
model: openai/zai-org/GLM-5.3
api_base: https://api.deepinfra.com/v1/openai
api_key: os.environ/DEEPINFRA_API_KEY
router_settings:
fallbacks: [{"glm": ["glm-backup"]}]
allowed_fails: 3
cooldown_time: 30
litellm_settings:
num_retries: 2
request_timeout: 60
O guia do proxy LiteLLM mostra a entrada da BroadNet completa. As duas entradas usam o prefixo genérico openai/ do LiteLLM com um api_base, o mesmo padrão do guia. Um gateway adiciona um salto e mais uma peça para manter rodando. Para um único app, cerca de 40 linhas no client, como acima, é suficiente.
Como testar o failover antes de precisar dele?
- Numa configuração de teste, aponte o principal para um host inacessível e confira se as requisições chegam ao reserva.
- Envie uma requisição propositalmente inválida e confira se ela não faz failover.
- Use uma chave principal inválida e confira se o 401 aparece como erro, não como uma troca silenciosa.
- Observe o breaker: depois de três falhas, o principal deve ser pulado sem esperar o timeout.
- Crie um alerta quando o reserva atender mais que uma pequena parte do tráfego. Um failover silencioso pode esconder um principal quebrado por dias.
O Router do LiteLLM aceita mock_testing_fallbacks=True em testes diretos para forçar um fallback.
Onde a BroadNet Inference se encaixa
O BroadRouter é o site da BroadNet, e a BroadNet Inference pode ser qualquer um dos itens da sua lista. Como principal, ela oferece o GLM 5.3 e o Qwen3.8 27B com ferramentas e saída estruturada documentadas, além do Gemma 4 VL 26B e do DeepSeek V4.1 Flash, numa única base URL sem conteúdo retido. Como reserva, é mais um endpoint compatível com a OpenAI para adicionar à lista. Nos dois casos, a lógica de failover é sua: a BroadNet não roteia entre provedores, e o self-service não tem SLA. Se você precisa de níveis de serviço contratados, eles só vêm com um acordo escrito separado. Compare os modelos, ou crie uma conta e teste sua cadeia com o crédito inicial de $5 no Gemma 4 VL 26B. O GLM 5.3 e o Qwen3.8 27B exigem uma recarga.
