Circuit Breaker in Node.js with Opossum: Don’t Let One Failing Service Bring Down the Whole System

Cascading Failures: When One Domino Topples the Entire System

In a Microservices architecture, it is common for a system to have 10 services calling each other. But consider this scenario: a third-party payment API suddenly responds slowly, taking 10 seconds, or crashes completely. Your ordering service keeps tirelessly sending requests and waiting for a response.

As a result, worker threads are fully occupied, creating a bottleneck. At this point, not only do payments fail, but features like viewing the shopping cart or searching also “go down.” This is a cascading failure—the worst-case scenario for backend developers.

To prevent this, the Circuit Breaker pattern is a mandatory solution. It works like an electrical fuse in a house. When the current (requests) overloads or an issue occurs, it automatically breaks the circuit to protect all downstream equipment (the system) from burning out.

Why Timeout and Retry Aren’t Enough

Many developers often rely on two basic methods to handle dependency errors, but both have critical weaknesses:

1. Retry Mechanism

If the target service is overloaded, repeatedly sending 3-5 retry requests only makes it crash faster. It’s like forcing an exhausted person to keep running.

2. Timeout

Setting a timeout helps release resources earlier. However, if you have 1,000 requests all waiting for a 5-second timeout, the system still consumes a significant amount of RAM and CPU to maintain those pending connections.

3. Circuit Breaker (The Smart Fuse)

This is a “fail-fast” mechanism. Instead of banging against a closed door, the system monitors the error rate. If this rate exceeds a threshold (e.g., 50% errors within 10 seconds), it opens the circuit (Open) immediately. All subsequent requests receive an error notification or fallback data without wasting time calling the broken service.

Practical Evaluation: Pros and Cons

Clear Benefits:

• Isolate the blast radius: A failure in Service A cannot spread to Service B.
• Self-healing system: The Half-Open mechanism allows the system to automatically probe and close the circuit once the service stabilizes.
• Smoother UX: Users receive a “Service temporarily under maintenance” response immediately instead of watching an infinite loading spinner.

Challenges:

• Parameter configuration: Choosing whether a 50% or 20% error threshold should trip the circuit requires real-world data (monitoring).
• Data state: You must ensure that fallback data does not disrupt the business logic of subsequent steps.

Implementing Opossum for Node.js Projects

In the Node.js ecosystem, Opossum is currently the standard library. It is lightweight, fully supports Closed, Open, and Half-Open states, and integrates perfectly with Async/Await functions.

When configuring complex options for Opossum, I often use toolcraft.app/en/tools/developer/json-formatter to validate the JSON structure. This helps avoid silly syntax errors that cause the Circuit Breaker to behave unexpectedly.

Step 1: Quick Installation

npm install opossum

Step 2: Real-world Code Example

Suppose you need to call a service to fetch product information. Wrap that logic in a Circuit Breaker:

const CircuitBreaker = require('opossum');

async function callExternalAPI() {
  // Simulate a real API call
  if (Math.random() > 0.7) throw new Error('API crashed!');
  return { status: 'success', data: 'Product A' };
}

const options = {
  timeout: 3000, // Trip if the API doesn't respond after 3 seconds
  errorThresholdPercentage: 50, // Open the circuit if over 50% of requests fail
  resetTimeout: 15000 // Attempt to reconnect after 15 seconds
};

const breaker = new CircuitBreaker(callExternalAPI, options);

// Set up fallback data
breaker.fallback(() => ({ status: 'fallback', data: 'Data from Cache (Offline)' }));

// Execute
breaker.fire()
  .then(console.log)
  .catch(console.error);

Step 3: Monitoring via Events

Don’t let the Circuit Breaker be a “black box.” Listen to events to push logs to Grafana or send alerts to Slack:

breaker.on('open', () => console.error('--- OPEN CIRCUIT: Service is failing heavily, stopping calls! ---'));
breaker.on('close', () => console.info('--- CLOSED CIRCUIT: Service has recovered, operating normally ---'));
breaker.on('halfOpen', () => console.log('--- HALF-OPEN CIRCUIT: Sending test request... ---'));

Hard-won Lessons from Production

Here are 3 tips to help you avoid having your solution backfire:

• Don’t be too sensitive: Setting errorThresholdPercentage too low (under 20%) can cause the circuit to trip constantly due to minor network flickers.
Share: