Padrão circuit breaker para APIs de terceiros em fluxos de trabalho visuais

Por que indisponibilidades de APIs de terceiros quebram mais de uma funcionalidade

Uma única API de terceiros costuma ficar no meio do trabalho diário: receber pagamentos, verificar endereços, sincronizar estoque, enviar mensagens, validar identidade. Quando esse fornecedor tem problemas, raramente quebra apenas um botão. Pode congelar fluxos inteiros que precisam daquela resposta para avançar.

Por isso o circuit breaker importa. Não é teoria — é uma forma prática de manter operações centrais funcionando mesmo quando uma integração está instável.

Lentidão e queda afetam de formas diferentes.

Quando uma API está lenta, seu fluxo ainda tenta ter sucesso, mas cada etapa espera. Usuários veem telas girando, times de suporte recebem chamados de “trancado” e jobs em background se acumulam. Lentidão é traiçoeira porque pode parecer que seu próprio sistema está falhando.

Quando uma API está caída, você recebe timeouts ou erros duros. Isso é mais claro, mas muitas vezes mais perigoso porque fluxos tendem a tentar novamente. Quando muitas requisições fazem retry ao mesmo tempo, você cria uma tempestade de tráfego que dificulta a recuperação e pode derrubar seu próprio sistema.

Sintomas comuns aparecem rápido: timeouts, filas crescendo, atualizações parciais e muita limpeza manual.

O dano real é a reação em cadeia. Se um provedor de tarifas de frete está lento, a colocação do pedido atrasa porque o fluxo se recusa a confirmar o pedido sem uma cotação. Se pagamentos caem, o suporte pode ficar bloqueado para emitir reembolsos, mesmo que o restante do sistema funcione.

Ignorar indisponibilidades não é uma opção. O objetivo é desenhar fluxos com caminhos de fallback claros, regras de bloqueio temporárias e alertas para que o negócio continue aceitando pedidos, atendendo clientes e registrando trabalho enquanto a integração se recupera.

Circuit breaker em termos simples

Um circuit breaker é um botão de segurança para chamadas de API. Quando um serviço de terceiros começa a falhar, o disjuntor impede que seu fluxo o martele repetidamente. Em vez de transformar uma única indisponibilidade em telas lentas, timeouts e jobs presos, você controla o raio de ação.

Um circuit breaker tem três resultados simples:

• Permitir a chamada quando o fornecedor parece saudável.
• Bloquear a chamada quando as falhas são altas, e seguir imediatamente um caminho de fallback.
• Tentar uma chamada de teste limitada após uma breve pausa para ver se o fornecedor voltou.

Se preferir nomes, são “closed”, “open” e “half-open”. Os nomes não são o ponto — previsibilidade é. Quando um fornecedor está doente, seu fluxo deve se comportar do mesmo jeito toda vez.

Isso não oculta erros. Você ainda registra falhas, mostra um status claro para usuários ou ops e alerta as pessoas certas. Você está escolhendo falhar rápido, encaminhar trabalho para uma alternativa mais segura ou pausar brevemente antes de testar novamente.

Escolha quais chamadas de API nunca podem parar o negócio

Circuit breakers funcionam melhor quando você é seletivo. Nem toda chamada de fornecedor merece proteção especial. Comece por etapas que, se bloqueadas, parem dinheiro, pedidos ou acesso de clientes.

Um método prático é acompanhar uma solicitação de usuário de ponta a ponta. Onde um timeout forçar o usuário a abandonar a tarefa, ou criar uma bagunça que a equipe precisa limpar depois?

Chamadas típicas que “não podem bloquear trabalho crítico” incluem pagamentos, frete e fulfillment, login/SSO/MFA, OTPs e mensagens de confirmação, e checagens de compliance ligadas a aprovações.

Separe também etapas de interface do usuário de jobs em background. Se alguém está esperando na tela de checkout, você precisa de uma decisão rápida: sucesso, fallback ou parar com uma mensagem clara. Para trabalho em background, como sincronizar números de rastreamento, retries mais lentos são aceitáveis desde que não bloqueiem o fluxo principal.

Comece pequeno para evitar aumento de escopo. Proteja 1–3 workflows primeiro, depois expanda.

Defina o que “fallback seguro” significa antes de construir qualquer coisa. Bons fallbacks são específicos e testáveis:

• Pagamentos: salve o pedido como “pagamento pendente” para que o carrinho não se perca.
• Frete: use uma tarifa em cache, uma tarifa fixa ou confirme o pedido e atrase a compra da etiqueta.
• Identidade: permita login por senha quando SSO está indisponível, ou mude para verificação por e-mail.
• Mensageria: enfileire SMS para envio posterior e ofereça um caminho alternativo quando possível.

No Business Process Editor da AppMaster, isso costuma virar um ramo limpo: a operação principal continua, enquanto a etapa dependente do fornecedor segue uma alternativa controlada.

Estados, limiares e timers que você pode explicar

Um circuit breaker é um botão de segurança. Na maior parte do tempo ele deixa chamadas passarem. Quando o fornecedor começa a falhar, ele muda para proteger seu fluxo de tempo perdido e acúmulo de erros.

Os três estados

Closed é o normal. Você chama a API e continua.

Se as falhas ultrapassarem um limite, o disjuntor vira Open. Você para de chamar o fornecedor por um curto período e roteia imediatamente para um fallback (valor em cache, trabalho enfileirado, fluxo alternativo).

Após um resfriamento, o disjuntor vai para Half-open. Você permite um pequeno número de chamadas de teste. Se elas tiverem sucesso, retorna para Closed. Se falharem, volta a Open.

O que medir

Use sinais que correspondam a como o fornecedor falha:

• Timeouts
• Erros HTTP 5xx
• Latência crescente (muito lenta para ser útil)
• Erros de conexão/DNS
• 429 rate limits

Em uma ferramenta de workflow visual, isso normalmente mapeia para checagens simples: código de status, tempo decorrido e saídas de erro específicas.

Limiar inicial e os dois timers chave

Comece com números fáceis de explicar e depois ajuste com base no tráfego real. Exemplos:

• Abra o disjuntor se 5–10 chamadas falharem dentro de 30–60 segundos.
• Ou abra se 20%–40% das chamadas falharem em uma janela móvel.
• Considere latência como falha quando exceder o que seu processo tolera (muitas vezes 2–5 segundos).

Depois defina dois timers:

• Tempo de cooldown (estado Open): geralmente 30 segundos a 5 minutos.
• Janela de teste Half-open: permita 1–5 chamadas de teste, ou uma janela curta como 10–30 segundos.

O objetivo é simples: falhar rápido quando o fornecedor está instável e recuperar automaticamente quando ele voltar.

Passo a passo: construir um circuit breaker em um workflow visual

A escolha de design mais importante é tomar a decisão “devemos chamar o fornecedor agora?” em um único lugar, não espalhada por todos os workflows.

1) Coloque a chamada ao fornecedor atrás de um bloco reutilizável

Crie um sub-processo (um bloco de workflow reutilizável) que todo workflow use quando precisar daquele fornecedor. Na AppMaster, isso se mapeia naturalmente para um Business Process que você pode chamar de endpoints ou automações. Mantenha-o estreito: entradas dentro, requisição ao fornecedor fora, mais um resultado claro de sucesso/erro.

2) Rastreie falhas com tempo, não apenas contagens

Registre cada resultado com timestamp. Armazene coisas como último sucesso, última falha, falhas dentro de uma janela, estado atual e um deadline de cooldown.

Persista esses campos em uma tabela para que o disjuntor sobreviva a reinícios e permaneça consistente entre múltiplas instâncias. PostgreSQL via Data Designer funciona bem para isso.

3) Defina mudanças de estado que você seguirá sempre

Mantenha as regras simples. Exemplo: se 5 falhas ocorrerem em 2 minutos, troque para Open. Enquanto Open, pule a chamada ao fornecedor até o cooldown passar. Após cooldown, vá para Half-open e permita uma tentativa controlada. Se funcionar, feche o disjuntor. Se falhar, reabra.

4) Ramifique o workflow: caminho do fornecedor vs caminho de fallback

Antes da requisição ao fornecedor, verifique o estado armazenado:

• Closed: chame o fornecedor e então atualize sucesso ou falha.
• Open: pule a chamada e execute o fallback.
• Half-open: permita uma tentativa limitada e então decida fechar ou reabrir.

Exemplo: se uma API de etiquetas de frete está caída, o fallback pode criar o pedido com status “Etiqueta pendente” e enfileirar um job de retry, em vez de bloquear o checkout ou o trabalho do armazém.

5) Faça-o compartilhado entre workflows

Se você tem múltiplos workflows e servidores, eles devem ler e escrever o mesmo estado do disjuntor. Caso contrário, uma instância pode continuar martelando o fornecedor enquanto outra já decidiu pausar.

Fallbacks que mantêm o trabalho fluindo

Um circuit breaker só ajuda se você decidir o que acontece quando a chamada é bloqueada. Um bom fallback mantém o usuário avançando, protege seus dados e torna a limpeza posterior previsível.

Escolha um fallback que corresponda à tarefa. Se um provedor de tarifas de frete está fora, talvez você não precise do preço exato para aceitar o pedido. Em um workflow visual, roteie a etapa de API falhada para um ramo de fallback que ainda produza um resultado utilizável.

Na prática, fallbacks geralmente são um destes:

• Usar um último valor conhecido em cache (com janela de frescor clara).
• Usar uma estimativa segura padrão, claramente rotulada.
• Encaminhar para revisão manual.
• Enfileirar o trabalho para retry posterior (job assíncrono).

A experiência do usuário importa tanto quanto a lógica. Não mostre um erro vago. Diga o que aconteceu e o que o usuário pode fazer a seguir: “Não conseguimos confirmar a tarifa agora. Você pode finalizar o pedido com um custo estimado de frete, ou salvá-lo para revisão.”

Planeje também para outages curtos vs longos. Uma interrupção curta (minutos) normalmente significa “continue, retry em background.” Uma interrupção longa (horas) pode exigir comportamento mais rigoroso, como revisão manual ou aprovações.

Por fim, registre cada fallback para que a reconciliação seja fácil. No mínimo, grave o tipo de fallback, detalhes da requisição original, o que foi retornado ao usuário (e se foi uma estimativa) e um status para acompanhamento.

Regras de bloqueio temporário e retries mais inteligentes

Retries descontrolados transformam pequenos problemas do fornecedor em indisponibilidades reais. Quando muitos workflows tentam novamente ao mesmo tempo, eles criam um pico (o problema do “thundering herd”). O fornecedor fica mais lento, suas filas crescem e você consome limites de taxa.

Retries devem ser previsíveis e limitados, e devem respeitar o estado do disjuntor. Uma política prática é:

• Mantenha retries máximos baixos (geralmente 2–3).
• Use backoff exponencial (por exemplo, 2s, 8s, 30s).
• Adicione jitter para que retries não se sincronizem.
• Limite o tempo total de retry (por exemplo, 60–90 segundos).
• Se o disjuntor estiver Open, não faça retry. Vá direto para o fallback.

Bloqueio temporário é relacionado, mas distinto. É para casos onde a resposta indica “isso não vai funcionar agora.” Regras comuns:

• 429 rate limit: bloqueie pelo período indicado em Retry-After (ou uma janela fixa segura).
• 401/403 falha de auth: bloqueie até credenciais serem renovadas, então teste uma vez.
• 5xx consistentes: bloqueie brevemente e depois permita um pequeno teste.

Durante um bloqueio, decida o que fazer com trabalho já em movimento: enfileirar, redirecionar ou degradar graciosamente (por exemplo, aceitar o pedido mas atrasar o envio do SMS).

Alertas que dizem o que fazer

Um circuit breaker só é útil se as pessoas souberem rápido e souberem o que fazer. O objetivo não é ruído — é uma mensagem clara quando o comportamento muda: chamadas estão sendo bloqueadas, fallbacks estão ativos ou o disjuntor ficou aberto por mais tempo que o esperado.

Gatilhos bons por padrão:

• Alertar quando o disjuntor abre.
• Alertar se ficar aberto além de um limite de tempo.
• Alertar em um aumento súbito de erros mesmo antes de abrir.

Faça alertas acionáveis. Inclua o fornecedor e endpoint, estado atual e quando mudou, o que os usuários sentirão, o que o workflow está fazendo agora (bloqueando, retrying, fallback) e um próximo passo sugerido.

Direcione alertas por severidade. Uma API de enriquecimento não crítica pode ir por email. Pagamentos, login ou envio de pedidos geralmente merecem uma paginação (page). Na AppMaster isso se mapeia bem para ramos que enviam email, Telegram ou SMS com base em uma flag de severidade.

Monitore um conjunto pequeno de métricas para ver se você está recuperando: chamadas bloqueadas e uso de fallback por fornecedor costumam ser suficientes.

Exemplo: indisponibilidade do fornecedor sem parar pedidos

Uma falha comum: seu provedor de tarifas de frete cai exatamente quando clientes estão finalizando compra. Se seu fluxo insistir em tarifas ao vivo durante a criação do pedido, uma única indisponibilidade pode parar os pedidos totalmente.

Em um dia normal, o pedido é criado, o workflow solicita tarifas ao vivo e o pedido é salvo com a transportadora e preço escolhidos.

Quando o fornecedor começa a falhar, chamadas dão timeout ou retornam 5xx. Quando seu limiar é atingido (por exemplo, 5 falhas em 2 minutos), o disjuntor abre.

Enquanto estiver Open, o fluxo para de chamar o provedor por uma janela curta (digamos, 10 minutos). Isso impede que um fornecedor defeituoso atrase o checkout para todos.

Em vez de bloquear o checkout, o fallback pode:

• Aplicar uma tarifa fixa (ou uma estimativa segura).
• Criar o pedido mesmo assim.
• Marcar como “Tarifa de frete pendente” para recálculo posterior.
• Salvar detalhes de erro do fornecedor para acompanhamento.

Na AppMaster, isso aparece como um ramo claro no Business Process Editor, apoiado por campos do Data Designer como shipping_rate_status e shipping_rate_source.

Verificações rápidas antes de liberar

Um circuit breaker deve se comportar da mesma forma sob estresse e em uma demo. Antes de lançar, confirme o básico:

• Limiar e cooldowns estão documentados e fáceis de alterar.
• Estado Open bloqueia chamadas imediatamente (sem esperar timeouts do fornecedor).
• Fallback é seguro para dinheiro e promessas ao cliente.
• Sondagens Half-open são limitadas a poucas chamadas de teste.
• Logs tornam o tempo e impacto fáceis de responder.

Gaste tempo extra na segurança do fallback. Um fallback que “mantém o trabalho andando” também pode criar risco financeiro. Se o provedor de pagamentos está fora, marcar pedidos como pagos é perigoso. Uma abordagem mais segura é “pagamento pendente”, com mensagem clara ao cliente.

Teste a recuperação de propósito. Force falhas, observe o disjuntor abrir, aguarde o cooldown e confirme que Half-open envia só uma pequena sondagem. Se tiver sucesso, deve fechar rapidamente. Se falhar, deve reabrir sem inundar o fornecedor.

Seus logs devem responder, em menos de um minuto: quem foi afetado, quando começou, qual etapa do workflow acionou o disjuntor e qual fallback foi usado.

Próximos passos: implemente o padrão na AppMaster

Escolha uma integração que possa prejudicar operações diárias se falhar (pagamentos, etiquetas de frete, SMS, sync de CRM). Construa o disjuntor ponta a ponta para essa chamada primeiro. Quando a equipe confiar no comportamento, repita o mesmo modelo para o próximo fornecedor.

Na AppMaster, modele o estado do disjuntor no PostgreSQL usando o Data Designer. Mantenha simples: um registro por fornecedor (ou endpoint) com campos como state, failure_count, last_failure_at, open_until e um curto last_error.

Então implemente a lógica no Business Process Editor com ramos legíveis. Clareza vence esperteza.

Um fluxo de construção prático:

1. Verifique o estado do disjuntor e bloqueie chamadas quando open_until estiver no futuro.
2. Chame a API do fornecedor e capture saídas de sucesso e erro.
3. Em caso de sucesso, zere contadores e feche o disjuntor.
4. Em caso de falha, incremente contadores e abra o disjuntor quando os limiares forem atingidos.
5. Roteie fluxos voltados ao usuário para um fallback (enfileirar trabalho, usar dados em cache ou permitir processamento manual).

Documente a decisão de fallback em linguagem simples para que suporte e ops saibam o que o usuário vê.

Quando o disjuntor abrir, notifique um responsável usando módulos de mensageria da AppMaster (email, SMS, Telegram). Inclua o que importa: fornecedor, endpoint, estado e a primeira ação recomendada.

Se você está construindo esses workflows na AppMaster, appmaster.io é um ponto prático para começar porque o mesmo Business Process visual pode alimentar endpoints, jobs em background e alertas com um estado de disjuntor compartilhado.