- Circuit breaker não é retry: ele para de tentar por um tempo para proteger o sistema
- Estados básicos: closed (normal), open (bloqueado), half-open (teste controlado)
- Persistência é obrigatória: o estado do breaker não pode ficar só “na memória” do workflow
- Combine com rate limit/backoff e DLQ para reprocessar depois sem duplicar
1) Defina o “serviço alvo” e o que conta como falha
Escolha uma dependência (ex.: API de pagamento, CRM, WhatsApp) e padronize o que é erro para você: timeouts, 5xx, 429, respostas inválidas, latência acima de X. Sem isso, o breaker vira loteria.
2) Modele os estados do breaker (closed/open/half-open)
Crie uma regra simples: (a) closed: chamadas liberadas; (b) open: bloqueia chamadas por um cooldown; (c) half-open: libera poucas chamadas de teste (1 ou um pequeno lote) e decide se fecha ou reabre.
3) Crie um registro persistente do breaker
Guarde em um lugar persistente: Postgres/Supabase/SQLite (se pequeno) ou Redis. Campos úteis: service_key, state, fail_count, window_start, opened_at, cooldown_seconds, last_error. Se você roda múltiplos workers, persistência é o que impede cada worker “achar” que está tudo bem.
4) Antes de chamar a API, faça o “pré-check”
No início do workflow (ou sub-workflow), leia o estado do breaker. Se state=open e ainda está no cooldown, não chame a API: vá para fallback (fila, e-mail interno, planilha de pendências, etc.). Se cooldown expirou, mude para half-open.
5) Execute a chamada com timeout e tratamento de erro
Faça a requisição (HTTP Request, node de app, etc.) com timeout definido. Capture erro e normalize: classifique 429/5xx/timeout. Evite deixar o node “explodir” sem você atualizar o estado do breaker.
6) Atualize o breaker após cada tentativa
Se sucesso: zere fail_count e feche (state=closed). Se falha: incremente fail_count na janela. Ao atingir o limite, abra (state=open, opened_at=agora). Em half-open, seja mais rígido: uma falha pode reabrir imediatamente.
7) Escolha o fallback (não é só desistir)
Fallback comum em automação: (a) enfileirar para reprocessar depois, (b) gravar em tabela “pendências”, (c) mandar alerta para canal interno, (d) responder 202 e processar async quando for webhook. O importante: não perder evento nem duplicar efeito.
8) Coloque observabilidade mínima
Registre transitions (closed→open, open→half-open, half-open→closed). Um log simples com correlation id e service_key já reduz muito o tempo de diagnóstico. Se der, alerte quando abrir e quando ficar abrindo/fechando em loop.
Quando circuit breaker é necessário (e quando é exagero)
Use circuit breaker quando uma dependência externa fica instável e seus retries começam a piorar a situação: você aumenta carga na API, estoura rate limit, atrasa filas e o n8n vira uma fábrica de erro.
É exagero para integrações raras e não críticas (ex.: puxar um relatório semanal) — nesses casos, retry com backoff e um alerta costumam bastar.
Arquitetura prática no n8n (um desenho mental)
Pense em três blocos: (1) Guardião (pré-check do breaker), (2) Chamada protegida (HTTP/app + timeout), (3) Pós-processamento (atualiza breaker + decide sucesso/fallback).
Se você tem vários workflows chamando o mesmo serviço, vale centralizar o breaker em um sub-workflow reutilizável (para não cada fluxo inventar seu próprio critério).
- Entrada do evento (webhook/cron/fila)
- Pré-check: ler estado do breaker por service_key
- Se open: ir para fallback (gravar pendência / enfileirar / alertar)
- Se closed/half-open: chamar API com timeout
- Atualizar estado do breaker (sucesso ou falha)
- Continuar o fluxo ou finalizar com fallback
Tabela de parâmetros (ponto de partida, ajuste conforme seu caso)
Não existe número mágico. Os valores abaixo são um ponto de partida comum; ajuste pelo comportamento real da API e pelo impacto no seu negócio (quanto custa atrasar vs. quanto custa insistir).
| Parâmetro | Sugestão inicial | Como ajustar na prática |
|---|---|---|
| Janela de erro (window) | 1 a 5 minutos | Aumente se a API oscila em rajadas; diminua se precisa reagir rápido |
| Limite de falhas | 3 a 10 falhas na janela | Aumente se você tolera falhas; diminua se a falha causa efeito cascata |
| Cooldown (open) | 30s a poucos minutos | Aumente se a API demora a voltar; reduza se ela recupera rápido |
| Half-open (teste) | 1 chamada de teste por vez | Aumente para pequeno lote se o custo de atraso for alto |
| Timeout de requisição | Curto o suficiente para não travar filas | Meça latência típica e evite esperar “para sempre” |
Erros comuns que fazem o breaker falhar
O circuito abre, mas continua chamando a API: geralmente é porque o estado não está persistido corretamente ou porque cada workflow usa uma chave diferente para o mesmo serviço.
O circuito nunca fecha: em half-open você está testando demais (vira closed na prática) ou seu critério de sucesso é rígido demais (qualquer instabilidade impede recuperação).
Você resolveu a cascata de erro, mas criou duplicidade: isso acontece quando o fallback reprocessa sem idempotência. Breaker protege disponibilidade; idempotência protege consistência.
- Guardar estado só em variável do workflow (perde em reinício/escala)
- Não tratar 429 como sinal de proteção (às vezes deveria abrir ou reduzir ritmo)
- Retry agressivo sem jitter (sincroniza pancadas e piora rate limit)
- Fallback sem trilha de auditoria (ninguém sabe o que ficou pendente)
Perguntas frequentes
Circuit breaker substitui retry no n8n?
Preciso de Redis para fazer circuit breaker no n8n?
Como escolher a chave (service_key) do breaker?
O que fazer com eventos durante o circuito aberto?
Leia também
Circuit breaker em automações (n8n/Make/Zapier): como evitar cascata de erros quando uma API cai
Guia prático para aplicar padrão circuit breaker em automações no n8n, Make ou Zapier: quando abrir/fechar, como detectar falhas, fallback, filas e alertas para não derrubar sua operação.
Ler →
Rate limit, retry e backoff: como parar de quebrar automação em API (n8n, Make, Zapier)
Guia direto para lidar com rate limit (429), retries e backoff em automações com APIs. Aprenda padrões práticos para n8n, Make e Zapier e evite falhas intermitentes, duplicidades e banimentos.
Ler →
Como usar Dead Letter Queue (DLQ) em automações: trate falhas sem perder eventos
Guia prático de Dead Letter Queue (DLQ) para automações: quando usar, como modelar eventos, reprocessar com segurança e evitar duplicidade em n8n/Make/Zapier.
Ler →
n8n vs Make para workflows long-running: filas, retries e tarefas que não podem falhar
Entenda qual ferramenta lida melhor com automações longas (minutos/horas), filas, rate limit e reprocessamento: n8n ou Make. Comparação prática com cenários reais no Brasil.
Ler →