Circuit Breakers

Automatically detect failing backends and stop sending traffic to them. Circuit breakers prevent cascade failures and give your upstream services time to recover.

Quickstart

Enable a circuit breaker on your route configuration to automatically trip when the backend begins to fail, giving it 30 seconds to recover before allowing new requests.

{
  "circuitBreaker": {
    "enabled": true,
    "failureThreshold": 5,
    "monitoringWindow": 60000,
    "recoveryTimeout": 30000,
    "successThreshold": 2
  }
}

Reference

Nolxy implements a per-route circuit breaker with three states:CLOSED (normal operation),OPEN (tripped, returns 503), andHALF-OPEN (probing for recovery).

Field	Type	Default	Required	Description
enabled	boolean	false	No	Whether the circuit breaker is active for this route.
failureThreshold	integer	5	No	Number of failures (5xx or timeouts) before the circuit opens.
monitoringWindow	integer (ms)	60000	No	Time window to count failures before resetting the count.
recoveryTimeout	integer (ms)	30000	No	How long the circuit stays OPEN before transitioning to HALF-OPEN to test recovery.
successThreshold	integer	2	No	Number of successful requests needed in HALF-OPEN state to fully close the circuit again.

Examples

Aggressive Breaker for Fragile Upstreams

Trip the circuit breaker after only 2 failures within a 10-second window, and wait a full minute before attempting to send traffic again.

{
  "circuitBreaker": {
    "enabled": true,
    "failureThreshold": 2,
    "monitoringWindow": 10000,
    "recoveryTimeout": 60000,
    "successThreshold": 1
  }
}

Common Errors

503 Service Unavailable

Circuit Breaker OPEN

Fix: The upstream backend is failing. The 503 response includes a Retry-After header indicating when the gateway will test the connection again. Ensure your upstream service is healthy.

HTTP/1.1 503 Service Unavailable
Retry-After: 30

{
  "error": "Service Unavailable",
  "message": "Circuit breaker is open",
  "statusCode": 503
}

Plan Requirements

Circuit Breakers are available on paid plans.