Configuration Strategies

Every project is different. This section helps you pick the right circuit breaker setup based on your integration's reliability profile and traffic patterns.

Strategy 1: Single Backend, Default Settings

When: Your integration talks to one backend and all endpoints have similar reliability.

This is the default — no configuration needed. All methods share one breaker, and the BALANCED preset works well for most backends.

integrations: {
  commerce: {
    location: "./integrations/commerce/index.server.ts",
    configuration: { /* ... */ },
    // No circuitBreaker config needed — BALANCED is the default
  },
}

Strategy 2: Slow or Unreliable Backend

When: Your backend has high latency (e.g., legacy ERP, slow SAP instance) or intermittent connectivity issues. The default 20-second timeout is too aggressive.

Use the TOLERANT preset to give the backend more room:

circuitBreaker: {
  preset: "TOLERANT",  // 60s timeout, 70% error threshold, 60s reset
},

If only specific endpoints are slow (e.g., search queries), consider selective method granularity instead of making the entire integration tolerant:

circuitBreaker: {
  preset: "BALANCED",
  granularity: "method",
  methods: ["searchProducts"],  // only search gets its own (more tolerant) breaker
},

Strategy 3: Latency-Sensitive Checkout Flow

When: You have a payment or checkout integration where slow responses are worse than fast failures. You'd rather show an error quickly than make the user wait.

integrations: {
  payment: {
    location: "./integrations/payment/index.server.ts",
    configuration: { /* ... */ },
    circuitBreaker: {
      preset: "FAST_FAILURE",  // 3s timeout, 40% threshold, 5s reset
    },
  },
}

Strategy 4: Mixed Reliability Across Integrations

When: You have multiple integrations with different reliability profiles — e.g., a fast product API and a flaky reviews service.

Configure each integration independently:

integrations: {
  commerce: {
    location: "./integrations/commerce/index.server.ts",
    configuration: { /* ... */ },
    circuitBreaker: { preset: "AGGRESSIVE" },  // fast, reliable backend
  },
  reviews: {
    location: "./integrations/reviews/index.server.ts",
    configuration: { /* ... */ },
    circuitBreaker: { preset: "TOLERANT" },  // flaky third-party
  },
}

Strategy 5: Isolating a Known-Flaky Endpoint

When: One specific endpoint fails independently of the rest (e.g., getReviews depends on a third-party service that has regular outages), and its failures are tripping the integration-level breaker, blocking healthy endpoints.

Use selective method-level granularity to give only that endpoint its own breaker:

circuitBreaker: {
  preset: "BALANCED",
  granularity: "method",
  methods: ["getReviews"],  // only getReviews gets its own breaker
},

Now when getReviews fails:

• getReviews breaker opens → returns fail-fast errors
• getProduct, getCategory, and all other methods continue working normally on the shared integration-level breaker

Strategy 6: Protecting Against Cascade Failures in High-Traffic Storefronts

When: Your storefront handles high traffic and a backend outage could cause request queues to build up, consuming all available connections and bringing down the entire middleware.

Use AGGRESSIVE or HARD_FAIL to trip the breaker quickly and shed load:

circuitBreaker: {
  preset: "HARD_FAIL",  // 10% errors, 2s timeout, 3 calls minimum
},

This trips after just 3 requests if more than 10% fail, with only a 3-second reset window. The breaker recovers quickly once the backend stabilizes.

Choosing the Right Preset

Is your backend fast and reliable?
├─ Yes → BALANCED (default) or AGGRESSIVE
└─ No
   ├─ Is it consistently slow? → TOLERANT
   ├─ Is it intermittently flaky? → TOLERANT or BALANCED with higher threshold
   └─ Do you need fast failure? → FAST_FAILURE or HARD_FAIL