Circuit Breaker — Complete Gateway Resilience Guide

In this tutorial, you will learn about Circuit Breaker. We cover key concepts, practical examples, and best practices to help you master this topic.

The Circuit Breaker Pattern monitors backend service health and stops sending requests when failures exceed a threshold. This prevents cascading failures and allows failing services time to recover.

What You'll Learn

You'll learn circuit breaker states, configuration, and how to implement them in API gateways.

Why It Matters

When one service fails, requests pile up and can cascade to other services. A circuit breaker detects failures early and fails fast, protecting the entire system.

Real-World Use

A payment service becomes slow due to a database issue. After 5 failures in 10 seconds, the circuit breaker opens. All payment requests are immediately rejected for 30 seconds. The payment service recovers, the circuit closes, and traffic resumes.

flowchart TD
    A[Closed] -->|Failures > threshold| B[Open]
    B -->|Timeout elapsed| C[Half-Open]
    C -->|Request succeeds| A
    C -->|Request fails| B

Implementation

import time
from functools import wraps

class CircuitBreaker:
    def __init__(self, failure_threshold=5, recovery_timeout=30):
        self.failure_threshold = failure_threshold
        self.recovery_timeout = recovery_timeout
        self.failure_count = 0
        self.state = "CLOSED"
        self.last_failure_time = None

    def call(self, func, *args, **kwargs):
        if self.state == "OPEN":
            if time.time() - self.last_failure_time > self.recovery_timeout:
                self.state = "HALF_OPEN"
            else:
                raise Exception("Circuit breaker is OPEN")
        try:
            result = func(*args, **kwargs)
            if self.state == "HALF_OPEN":
                self.state = "CLOSED"
                self.failure_count = 0
            return result
        except Exception as e:
            self.failure_count += 1
            self.last_failure_time = time.time()
            if self.failure_count >= self.failure_threshold:
                self.state = "OPEN"
            raise e

Common Mistakes

| Mistake | Fix | |---------|-----| | No recovery time | Circuit opens and never recovers | Always set recovery timeout | | Circuit breaker without fallback | Users see 500 errors | Return cached or degraded response | | Too low threshold | Normal traffic fluctuations trigger circuit | Set threshold based on normal error rates | | Not logging state changes | Cannot debug circuit breaker behavior | Log every state transition | | Single circuit for all endpoints | One bad endpoint blocks all | Per-endpoint circuit breakers |

What's Next

Learn about Caching at the API Gateway layer.