# Circuit Breaker: guia para implementar na aplicação

> O circuit breaker é um padrão de resiliência que interrompe chamadas a um serviço com falhas, evitando sobrecarga e efeitos cascata. A implementação exige definir limiares de erro, estados (fechado, aberto, meio-aberto) e uma estratégia de fallback, além de monitoramento contínuo para não mascarar falhas reais.

*TNT Web · Apps e Software · 16 de setembro de 2026 · Jonas Ribaldo*

Implementar circuit breaker exige definir limiares, estados e fallback. Este guia passo a passo mostra como configurar a proteção, testar e monitorar, com cuidados para não mascarar falhas reais.

Implementar circuit breaker exige definir limiares, estados e fallback. Este guia passo a passo mostra como configurar a proteção, testar e monitorar, com cuidados para não mascarar falhas reais.

Antes de começar, você precisa de uma aplicação com chamadas a serviços externos, uma biblioteca de resiliência compatível com sua stack e acesso a métricas. O resultado esperado é isolar falhas e evitar que uma indisponibilidade derrube todo o sistema.

## Passo 1: Defina o limiar de falhas

Escolha quantas falhas consecutivas acionam a abertura do circuito. Um valor comum é 5 erros em 10 segundos, mas ajuste conforme o volume de chamadas. Erro comum: definir um número fixo sem considerar picos de tráfego.

## Passo 2: Configure os estados

Implemente os três estados: fechado (opera normalmente), aberto (bloqueia chamadas) e meio-aberto (testa a recuperação). No meio-aberto, permita uma chamada de teste. Erro comum: deixar o circuito aberto por tempo indeterminado, sem tentativa de recuperação.

## Passo 3: Escolha a ação de fallback

Defina o que fazer quando o circuito está aberto: retornar cache, valor padrão ou erro amigável. Uma dica é usar fallback que não dependa do mesmo serviço falho. Erro comum: fallback que também chama o serviço indisponível.

## Passo 4: Monitore e ajuste

Acompanhe métricas de abertura, tempo em cada estado e taxa de sucesso no meio-aberto. Ajuste os limiares com base nos dados. Erro comum: não instrumentar o circuito e só descobrir problemas em produção.

## Passo 5: Teste com falhas simuladas

Use injeção de falhas ou mocks para validar a transição entre estados. Verifique se o fallback responde corretamente e se o circuito reabre após o tempo definido. Erro comum: testar apenas o caminho feliz.

## Checklist rápido

- Limiar de falhas definido e documentado.
- Estados fechado, aberto e meio-aberto implementados.
- Fallback independente do serviço protegido.
- Métricas de monitoramento ativas.
- Testes com falhas simuladas realizados.

## FAQ

### O que é circuit breaker?

É um padrão de projeto que permite construir serviços tolerantes a falhas, evitando que uma falha se propague. No mercado financeiro, a B3 utiliza um mecanismo semelhante para amortecer movimentos bruscos, segundo a Wikipedia.

### Quando devo usar circuit breaker?

Use quando sua aplicação depende de serviços externos que podem falhar. O padrão evita chamadas repetidas a um serviço indisponível, protegendo recursos e melhorando a experiência do usuário.

### Qual a diferença entre circuit breaker e retry?

Retry tenta novamente a mesma chamada; circuit breaker interrompe as tentativas após um limite de falhas. Eles podem ser combinados, mas o circuit breaker evita sobrecarga no serviço falho.

### Como escolher o limiar de falhas?

Baseie-se no volume de chamadas e na criticidade. Monitore e ajuste. Não existe valor universal; comece conservador e refine com dados reais.

### O que fazer quando o circuito está aberto?

Execute o fallback definido: retornar cache, valor padrão ou mensagem de erro. O importante é não deixar o usuário sem resposta e não sobrecarregar o serviço falho.

### Circuit breaker pode mascarar problemas?

Sim, se o fallback for usado indiscriminadamente. Monitore as aberturas e investigue as causas. O objetivo é proteger, não esconder falhas.

---

Fonte (canonical): https://tntweb.com.br/apps-e-software/circuit-breaker-guia-para-implementar-na-aplicacao/