Configuration Strategies

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
},

The timeout comes from the preset and applies to every method of the integration. If only some endpoints are slow (e.g., search queries), pick a preset whose timeout covers the slowest of them. Method-level granularity won't give them more time: a method-level breaker uses the same preset as the rest of the integration.

If those endpoints are allowed to time out and you only want their timeouts to stop opening the breaker for every other method, isolate them as described in Strategy 5.

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