Configuration Reference

Configuration Reference

Fuse configurations are immutable and constructed using the type-safe CircuitBreakerConfig.builder().

---

Configuration Parameter Matrix

Parameter	Type	Default	Constraints	Description
failureThreshold	int	5	≥ 1	Number of consecutive recorded failures required to trip the circuit from CLOSED to OPEN.
successThreshold	int	3	≥ 1	Number of consecutive successful probe executions in HALF_OPEN required to reset the circuit to CLOSED.
timeout	Duration	60s	Non-null, > 0	Duration the circuit remains in OPEN before allowing probe calls via HALF_OPEN.
recordException	Predicate<Exception>	e -> true	Non-null	Functional filter deciding whether a thrown exception counts towards the failure counter.

---

Exception Classification Strategy

By default, every thrown exception is recorded as a failure. In production web applications, this default is often suboptimal: client-side errors (such as HTTP 400 Bad Request, 401 Unauthorized, or domain validation errors) represent normal business logic rejections, not downstream infrastructure failure.

Tripping a circuit breaker due to client validation mistakes denies service to valid users unnecessarily.

Example: Selective Exception Filtering

Configure the predicate to strictly record connectivity, network timeout, and remote 5xx server errors:

CircuitBreakerConfig config = CircuitBreakerConfig.builder()
        .failureThreshold(5)
        .timeout(Duration.ofSeconds(20))
        .recordException(ex -> {
            // Count standard network and connection I/O errors
            if (ex instanceof IOException || ex instanceof TimeoutException) {
                return true;
            }
            
            // For HTTP client wrappers, inspect the status code
            if (ex instanceof RemoteHttpException httpEx) {
                // Record 5xx Server Errors & 429 Too Many Requests
                return httpEx.getStatusCode() >= 500 || httpEx.getStatusCode() == 429;
            }

            // Ignore 4xx client errors (400, 404, 422)
            return false;
        })
        .build();

---

Tuning Recommendations by Workload Profile

High-Throughput Services (> 500 req/sec)

In services handling sustained high volume, a threshold of 5 can be tripped too quickly by minor transient network blips:

CircuitBreakerConfig highThroughputConfig = CircuitBreakerConfig.builder()
        .failureThreshold(15)             // Require 15 consecutive failures
        .successThreshold(5)              // Require 5 clean probes
        .timeout(Duration.ofSeconds(10))  // Re-test quickly (10s)
        .build();

Low-Throughput or Critical Financial APIs (< 10 req/sec)

For low-frequency integrations (e.g., payment gateways or fraud detection), failures indicate severe downstream outages. Fail fast:

CircuitBreakerConfig paymentGatewayConfig = CircuitBreakerConfig.builder()
        .failureThreshold(3)              // Trip after 3 consecutive failures
        .successThreshold(2)              // 2 successful probes to recover
        .timeout(Duration.ofSeconds(60))  // Stay open for 1 minute
        .build();