Um circuit breaker de gateway de API de LLM impede que um aplicativo envie repetidamente tráfego para uma rota que já está falhando. Sem essa proteção, um timeout pode acionar retries, os retries podem acionar tentativas de fallback, as tentativas de fallback podem acionar mais erros de provedor, e o app pode transformar um único incidente upstream em um loop de falha do provedor.
O objetivo não é substituir retries ou o fallback de modelo. O objetivo é decidir quando uma rota está degradada o suficiente para que o gateway pare de tentar usá-la por um curto período, envie depois uma sonda controlada e escolha um resultado mais seguro enquanto o breaker estiver aberto: fallback, fila, degradação ou fail closed.
Flatkey é relevante porque a flatkey.ai posiciona publicamente o produto em torno de uma única chave de API, uma base URL compatível com OpenAI em https://router.flatkey.ai/v1, roteamento, faturamento unificado, analytics de uso, controles de dashboard, troca automática, balanceamento de carga e limites de quota. Esses são pontos centrais úteis para trabalho de confiabilidade. Eles não eliminam a necessidade de definir uma política clara de circuit breaker de gateway de API de LLM para os fluxos de trabalho do seu próprio aplicativo.
Resposta rápida: o que um circuit breaker de API gateway para LLM deve fazer
Um circuit breaker de API gateway para LLM prático tem três estados de rota e um caminho de fail-closed. Mantenha a política simples o suficiente para que os engenheiros de plantão possam explicá-la durante um incidente.
| Estado | Comportamento do Gateway | O que o altera | Evidências a registrar |
|---|---|---|---|
| Fechado | O tráfego pode usar o provedor, modelo, família de endpoint, conta ou grupo de rotas. | Taxa de erro, taxa de timeout, latência, respostas de sobrecarga ou probes de saúde com falha cruzam o limite. | ID da política de rota, modelo selecionado, provedor, família de endpoint, latência, código de status, contagem de retries e custo. |
| Aberto | O gateway para de enviar tráfego normal para a rota com problema durante uma janela de cooldown. | O cooldown expira ou um operador permite manualmente um probe. | Motivo do breaker, horário de abertura, contagem de tentativas bloqueadas, rota de fallback, decisão de fila ou motivo de fail-closed. |
| Meio aberto | O gateway permite um número limitado de solicitações de probe antes de restaurar o tráfego. | Probes bem-sucedidos fecham o breaker; probes com falha o abrem novamente. | Tamanho da amostra de probe, workflow de probe, resultado do probe, latência, uso e aprovação do proprietário da rota. |
| Fail closed | O gateway recusa rotear a solicitação porque o problema não é de saúde do provedor. | Risco de autenticação, política, quota, segurança, limite de dados, solicitação inválida ou efeito colateral de ferramenta. | Motivo da interrupção, proprietário, mensagem visível ao usuário e caminho de correção. |
Por que as tentativas criam loops de falha do provedor
As tentativas são úteis quando uma solicitação falha por um motivo transitório. Elas se tornam perigosas quando cada solicitação do usuário cria várias chamadas upstream adicionais, especialmente durante uma indisponibilidade ou janela de sobrecarga do provedor. Um loop de tentativas pode consumir limites de taxa, gastar cota, aumentar a latência e ocultar a falha original atrás de um erro final.
Um disjuntor muda a questão das tentativas. Em vez de perguntar: "Devo tentar novamente esta solicitação?", o gateway pergunta: "Esta rota está saudável o suficiente para receber mais tráfego agora?" Essa visão em nível de rota é importante para cargas de trabalho de LLM porque cada solicitação pode ser cara, demorada, em streaming, usar ferramentas e ser visível para o cliente.
O padrão de design em nuvem da Microsoft para disjuntores descreve a mesma ideia central para serviços remotos: após falhas repetidas, o circuito se abre para que o aplicativo não continue tentando uma operação que provavelmente falhará. Para uma rota de IA, o mesmo padrão precisa de limites específicos de LLM: comportamento do modelo, família do endpoint, gasto de tokens, estado de streaming, efeitos colaterais de ferramentas, classe de dados e aprovação de fallback.
Classifique os erros antes que cheguem ao breaker
A maneira mais rápida de construir um mau circuit breaker de API de IA é contar toda falha como saúde do provedor. Isso cria falsos positivos. Também pode esconder problemas que o proprietário do app deve corrigir.
| Erro ou evento | Decisão do breaker | Motivo | Resultado padrão |
|---|---|---|---|
| Provider 500, 503, overload, unavailable, connection failure, repeated upstream timeout | Conte para a saúde da rota. | Esses são sinais plausíveis de saúde do provedor, da rota, de capacidade ou da rede. | Tente novamente dentro de um orçamento apertado e, em seguida, abra o breaker da rota se os limites forem ultrapassados. |
| 429 request-rate limit | Classifique com cuidado. | Um sinal de sobrecarga em todo o provedor e um pico criado pelo app exigem tratamentos diferentes. | Reduza a taxa, recue ou abra apenas a rota específica que realmente está saturada. |
| 429 monthly quota, exhausted credits, or spend limit | Não conte como saúde do provedor. | Esta é uma condição de orçamento ou do proprietário da conta. | Falhe fechado, alerte o responsável pelo orçamento ou encaminhe apenas se existir um orçamento pré-aprovado. |
| 401 auth, incorrect key, organization membership, IP allowlist, unsupported region | Não conte como saúde do provedor. | A solicitação não tem permissão para usar a rota. | Falhe fechado e corrija credenciais, conta, IP ou política de região. |
| Invalid request, unsupported parameter, unsupported model, malformed schema | Não conte como saúde do provedor. | O app enviou um formato de solicitação que a rota não consegue atender. | Corrija a solicitação ou escolha um modelo compatível antes de rotear. |
| Safety, moderation, DLP, compliance, or unapproved data-class block | Nunca ignore com fallback. | Encaminhar para outro modelo pode cruzar um limite de política. | Falhe fechado e registre a decisão de política. |
| Tool already executed, partial stream already shown, user cancelled request | Não reexecute silenciosamente. | O app pode criar efeitos colaterais duplicados ou mesclar duas saídas do modelo. | Marque como incompleto, exija uma nova tentativa explícita do usuário ou use um caminho de recuperação idempotente. |
O guia de códigos de erro da OpenAI é um exemplo útil de por que essa taxonomia importa: ele separa problemas de autenticação e de allowlist de IP, problemas de região não suportada, limites de taxa, esgotamento de quota, erros de servidor, sobrecarga e desacelerações repentinas na taxa de requisições. A documentação da Anthropic e do Google Gemini faz distinções semelhantes entre limites de taxa, condições de sobrecarga/indisponibilidade, solicitações inválidas e problemas de permissão ou quota. Seu circuit breaker de gateway de API de LLM deve manter essas classes separadas antes de abrir uma rota.
Especifique o Breaker para o Menor Caminho que Explica a Falha
Um breaker muito amplo causa tempo de inatividade desnecessário. Um breaker muito estreito permite que o mesmo loop de falha do provedor continue por caminhos próximos. Especifique o breaker para a menor dimensão de rota que explique o incidente.
| Escopo | Usar Quando | Risco se o Escopo Estiver Errado |
|---|---|---|
| Provedor | Vários modelos do mesmo provedor estão indisponíveis ou sobrecarregados. | Amplo demais se apenas um modelo, conta ou família de endpoints estiver falhando. |
| Modelo | Uma família de modelos apresenta erros repetidos de 5xx, timeout ou rota não suportada. | Restrito demais se a conta upstream ou o provedor estiver saturado. |
| Família de endpoints | Chat funciona, mas as rotas de Responses, imagem, vídeo, Anthropic Messages ou Gemini se comportam de forma diferente. | Mesclar famílias de endpoints pode ocultar falhas específicas do protocolo. |
| Conta, grupo, região ou caminho de fornecedor | Somente uma conta upstream, grupo de roteamento, região ou caminho de fornecedor está falhando. | Não isolar pode desperdiçar capacidade saudável em outro lugar. |
| Fluxo de trabalho | Chamadas de ferramenta, streaming, jobs em lote ou chat voltado ao cliente têm regras diferentes de segurança e repetição. | Uma rota segura para enriquecimento em lote pode não ser segura para streams de usuários ao vivo. |
Para usuários da Flatkey, isso significa que você deve testar a partir do fluxo de trabalho e da rota que realmente planeja usar. O snapshot atual da API de preços da Flatkey para este artigo retornou 638 linhas de modelos, 23 fornecedores e famílias de endpoints para OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini generateContent, geração de imagens e vídeo da OpenAI. Trate isso como evidência datada de 18 de junho de 2026, e não como um contrato permanente de rota.
Defina Limiares que Correspondam ao Tráfego de LLM
Um circuit breaker de gateway de API de LLM não deve abrir por causa de uma única falha isolada. Também não deve esperar até que cada solicitação do cliente esteja falhando. Use limiares que combinem volume mínimo de tráfego, taxa de falha, latência e cooldown.
| Threshold | Practical Starting Point | Why It Matters |
|---|---|---|
| Tamanho mínimo da amostra | Abra somente depois que um número suficiente de solicitações ou sondas tiver sido observado. | Evita que uma única conclusão cara abra uma rota global. |
| Taxa de falha | Acompanhe falhas upstream passíveis de nova tentativa separadamente das falhas pertencentes ao app. | Impede que erros de autenticação, quota e solicitação malformada contaminem a saúde da rota. |
| Limiar de latência ou timeout | Use orçamentos de timeout específicos por endpoint para caminhos de chat, streaming, imagem e vídeo. | Um bom limiar para chat pode estar errado para vídeo ou geração em lote. |
| Cooldown de abertura | Mantenha a rota aberta por tempo suficiente para interromper tempestades de retries e, então, faça sondagens. | Protege tanto o provedor quanto sua própria fila de solicitações. |
| Limite de sondas em half-open | Permita um pequeno número controlado de solicitações de teste antes de fechar. | Evita um pico total de tráfego quando um provedor está apenas parcialmente recuperado. |
| Teto de custo | Defina um gasto estimado máximo para retries, fallback e sondas. | Evita que a recuperação de confiabilidade se torne um incidente de faturamento. |
Limites de taxa fazem parte da discussão sobre limiares. O guia de rate limits da OpenAI explica que limites de taxa protegem contra abuso, garantem acesso justo e ajudam a gerenciar a carga agregada. Se seu app continuar fazendo retries em uma rota limitada por taxa, seu próprio padrão de tráfego pode se tornar o incidente. O circuit breaker de gateway de API de LLM deve მუშაობar com pacing no lado do cliente, enfileiramento e controles de quota, não contra eles.
Decida o que acontece enquanto o breaker está aberto
Abrir um breaker só é útil se o gateway tiver uma próxima ação definida. Não permita que toda rota aberta faça fallback automaticamente para qualquer modelo disponível.
| Ação no estado aberto | Quando usar | Guardrail necessário |
|---|---|---|
| Rota de fallback | O modelo ou provedor de backup já está aprovado para o fluxo de trabalho. | Execute as mesmas verificações de eval, schema, tool, data-boundary e custo antes da produção. |
| Fila | O job é assíncrono ou a experiência do usuário pode tolerar atraso. | Preserve os metadados de owner, customer, model, cost e retry. |
| Degradar | Um resultado parcial de menor risco é aceitável, como uma resposta em cache ou um recurso reduzido. | Torne o estado degradado visível para o app e os logs. |
| Falhar fechado | A solicitação tem risco de política, orçamento, segurança, autenticação, região ou efeito colateral. | Retorne um erro claro e alerte o owner correto em vez de tentar outro modelo. |
A documentação pública do Vercel AI Gateway descreve fallbacks de modelo como um padrão de gateway com modelos de backup em ordem. Use isso apenas como evidência de categoria. No seu próprio stack, fallback é uma decisão separada de aprovação. O breaker decide se uma rota está saudável no momento; fallback decide se outra rota está autorizada a atender a mesma solicitação.
Streaming E Chamadas de Ferramentas Precisam De Paradas Extras
O streaming torna mais fácil esconder um ciclo de falha do provedor. Se o aplicativo reiniciar silenciosamente uma solicitação após uma saída parcial, um usuário pode ver uma resposta mesclada de duas tentativas. As chamadas de ferramentas acrescentam um segundo problema: uma nova tentativa ou fallback pode duplicar um reembolso, atualização de ticket, e-mail, gravação em banco de dados ou ação externa.
Use estas regras na política do disjuntor do gateway de API de LLM:
- Antes da primeira saída: retry ou fallback podem ser permitidos se a rota estiver aprovada e o disjuntor estiver fechado ou semiaberto.
- Depois da primeira saída: marque o stream como incompleto e exija retry explícito do usuário em vez de fallback silencioso.
- Após a execução da ferramenta: não reproduza a menos que a ferramenta seja idempotente e a operação tenha uma chave de repetição.
- Após um bloqueio de política: falhe de forma fechada. Não direcione para outro modelo para contornar o bloqueio.
Isso se combina com os guias estratégia de retry de API de IA, checklist de fallback de modelo e balanceamento de carga e failover de API de IA. O disjuntor deve compartilhar a mesma taxonomia de falhas desses playbooks.
Campos de Observabilidade para Revisão do Circuit Breaker
Se uma solicitação é bem-sucedida apenas porque o gateway ignorou silenciosamente uma rota com falha, o incidente ainda precisa ficar visível. A documentação do AI Gateway da Cloudflare fornece um exemplo público de padrões de observabilidade de gateway de IA: logs de requisição podem incluir provedor, status, tokens, custo e duração, e metadados personalizados podem rotular solicitações para filtragem posterior. Os logs do seu gateway devem fornecer o mesmo nível de evidência da rota para as decisões do breaker.
| Campo | Por que os Operadores Precisam Dele |
|---|---|
| Breaker policy ID and version | Mostra qual regra abriu, fechou ou contornou a rota. |
| Breaker state at decision time | Explica se a rota estava fechada, aberta, meio aberta ou fail-closed. |
| Requested model, selected model, provider, account, group, and endpoint family | Separa a intenção do usuário da decisão de rota do gateway. |
| Error class per attempt | Distingue falhas upstream de erros de autenticação, cota, requisição inválida, política e ferramenta. |
| Latency, timeout, retry count, and probe result | Mostra se a rota falhou lentamente, falhou rapidamente ou se recuperou durante a sondagem em meio aberto. |
| Partial-output flag and tool side-effect status | Impede incidentes ocultos de saída mista ou ação duplicada. |
| Usage, cost, quota owner, and final disposition | Conecta a recuperação de confiabilidade a gastos, orçamentos e responsabilização. |
O artigo complementar logs de observabilidade da API de IA aprofunda o registro de incidentes. Para circuit breakers, priorize o estado da rota e o motivo exato pelo qual uma solicitação foi bloqueada, sondada, roteada, enfileirada ou falhou fechado.
Plano de Implantação Flatkey Para Políticas de Circuit Breaker
Use esta abordagem em fases antes de confiar em um circuit breaker de gateway de API de LLM para tráfego de clientes por meio da Flatkey ou de qualquer gateway compatível com OpenAI.
- Criar uma chave de staging: mantenha os testes do breaker separados do tráfego de clientes em produção.
- Confirmar a rota base: aponte um cliente compatível com OpenAI para
https://router.flatkey.ai/v1e verifique o modelo, a família de endpoint, a linha de uso e a visibilidade no dashboard. - Registrar o catálogo de rotas: salve a página de preços da Flatkey e a resposta da API de preços na data do rollout para que as suposições sobre rotas e preços possam ser auditadas.
- Definir a taxonomia de erros: decida quais erros contam para a saúde da rota e quais falham de forma fechada antes que o breaker os veja.
- Começar com um fluxo de trabalho: aplique o breaker a uma rota de modelo, uma família de endpoint e uma classe de tráfego antes de expandir.
- Forçar testes de falha: simule timeout do provedor, 500, 503, 429 por taxa de requisições, esgotamento de quota, falha de autenticação, requisição malformada, stream parcial e efeito colateral da ferramenta.
- Verificar o comportamento em estado aberto: confirme que as ações de fallback, fila, degradação ou fail-closed correspondem à matriz de aprovação.
- Revisar logs e faturamento: confirme que o estado do breaker, a rota selecionada, o uso, o custo e o proprietário da quota estejam visíveis após cada teste.
- Definir rollback: desative a política se ela se abrir de forma ampla demais, ocultar erros pertencentes ao app ou gerar gastos inesperados.
Modelo de Política de Disjuntor
Este modelo não é um contrato de API da Flatkey. Trate-o como um artefato de revisão para os responsáveis de engenharia, produto, finanças e segurança.
{
"policy_id": "support-chat-provider-breaker-v1",
"workflow": "customer-support-chat",
"environment": "production",
"route_scope": {
"provider": "primary-provider",
"model": "primary-approved-model",
"endpoint_family": "openai-chat-completions",
"traffic_class": "customer-visible-stream"
},
"count_toward_breaker": [
"upstream_5xx",
"provider_overloaded",
"provider_unavailable",
"upstream_timeout",
"connection_reset"
],
"fail_closed_before_breaker": [
"auth_error",
"ip_allowlist_error",
"unsupported_region",
"quota_exhausted",
"invalid_request",
"schema_incompatible",
"safety_or_policy_block",
"unapproved_data_class",
"tool_side_effect_already_committed"
],
"thresholds": {
"window_seconds": 60,
"minimum_requests": 20,
"failure_ratio_to_open": 0.5,
"timeout_ratio_to_open": 0.4,
"open_cooldown_seconds": 90,
"half_open_probe_requests": 3,
"max_total_attempts_per_request": 2
},
"open_state_action": {
"default": "fail_closed",
"allowed_fallback_policy_ids": [
"support-chat-fallback-v1"
],
"allow_after_partial_output": false,
"allow_after_tool_side_effect": false
},
"logging": {
"record_breaker_state": true,
"record_route_scope": true,
"record_error_class_per_attempt": true,
"record_probe_results": true,
"record_usage_cost_and_quota_owner": true
}
}Perguntas frequentes
O que é um circuit breaker de gateway de API de LLM?
Um circuit breaker de gateway de API de LLM é uma política de integridade de rota que impede o tráfego normal de atingir um modelo, provedor, conta ou família de endpoints com problemas após falhas repetíveis recuperáveis. Ele abre por uma janela de resfriamento, permite sondas limitadas em half-open e só fecha depois que a rota parece saudável novamente.
Quais erros de API de LLM devem abrir um circuit breaker?
Erros 5xx do lado do provedor, sobrecarga, respostas de indisponibilidade, falhas de conexão e timeouts upstream repetidos são candidatos típicos. Erros de autenticação, falhas de allowlist de IP, regiões sem suporte, quota esgotada, solicitações malformadas, bloqueios de política e efeitos colaterais de ferramentas normalmente devem falhar fechado em vez de abrir um breaker de saúde do provedor.
Como um circuit breaker é diferente de retry ou fallback?
Retry decide se uma solicitação deve ser tentada novamente. Fallback decide se outra rota aprovada pode atender a solicitação. Um circuit breaker decide se uma rota deve receber tráfego normal em absoluto enquanto parece estar com problemas.
Os circuit breakers devem se aplicar a respostas de LLM em streaming?
Sim, mas com limites mais rígidos. Um breaker pode proteger a rota antes do primeiro token visível. Após saída parcial ou um efeito colateral de ferramenta, o aplicativo não deve repetir silenciosamente nem fazer fallback, a menos que o fluxo de trabalho seja explicitamente projetado para recuperação idempotente.
Verificação Final Antes de Ativar o Disjuntor
Antes de ativar um disjuntor de gateway de API de LLM, faça uma pergunta: se esta rota abrir durante um incidente do provedor, a equipe consegue explicar o que falhou, por que o tráfego normal parou, para onde o tráfego foi em seguida, quanto custou e como fechar ou reverter a política?
Se a resposta for não, mantenha o disjuntor em staging. Se a resposta for sim, use o acesso centralizado a modelos, o roteamento, a visibilidade de uso, o faturamento e os controles de cota da Flatkey como parte do ciclo de revisão. Quando estiver pronto para validar rotas por trás de um gateway compatível com OpenAI, obtenha uma chave e comece com um fluxo de trabalho, uma rota de modelo e uma política de disjuntor.
