Circuit Breaker

The circuit breaker prevents cascading failures by automatically stopping requests to an unhealthy origin server when error thresholds are exceeded.

States & Lifecycle

Circuit Breaker State Machine

         CLOSED  ─────────────────────────────────────────────────────────────┐
          │  (normal operation)                                              │
          │                                                                  │
          │  failureCount >= failureThreshold                               │
          ▼                                                                  │
         OPEN                                                               │
          │  (origin blocked, serve stale cached content or return 503)      │
          │                                                                  │
          │  after recoveryTimeoutMs                                        │
          ▼                                                                  │
       HALF_OPEN                                                             │
          │  (allow one probe request to test origin health)                 │
          │                                                                  │
          ├── probe succeeds  ──────────────────────────────────────────────┘
          │
          └── probe fails  ──→  OPEN (reset timer)

Dashboard Setup & Configuration

You can monitor and configure the Circuit Breaker directly inside the EdgeWrap Dashboard:

Navigate to your project in the dashboard at https://app.edgewrap.pro.
Go to the Performance page and select the Circuit Breaker tab.
View the current status of the circuit (CLOSED, OPEN, or HALF_OPEN) along with recent health check histories and failure metrics.
If the circuit is currently OPEN and you want to bypass the wait period after recovering your server, click Reset Circuit to force it back to CLOSED.
Configure thresholds (sequential failure count, success threshold, request timeouts) under the configuration card and click Save Settings.

API Configuration

Alternatively, you can manage the circuit breaker configuration and reset states programmatically:

Param	Type	Required	Description
failureThreshold	integer (1–50)	optional	Consecutive failures before transitioning to OPEN.(default: 5)
successThreshold	integer (1–20)	optional	Consecutive successes in HALF_OPEN before transitioning back to CLOSED.(default: 2)
recoveryTimeoutMs	integer (1000–300000)	optional	Cooldown duration in milliseconds to stay in OPEN state before probing.(default: 30000)
requestTimeoutMs	integer (500–30000)	optional	Origin request duration limit in milliseconds before counting as a timeout failure.(default: 10000)
errorThresholdPercent	float (0–100)	optional	Error rate % over a sliding window that triggers OPEN.(default: 50)

Configure circuit breaker thresholds via API

curl -X PATCH https://server.edgewrap.pro/v1/projects/prj_abc123/circuit-breaker/config \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "failureThreshold": 3,
    "recoveryTimeoutMs": 15000,
    "requestTimeoutMs": 5000
  }'

Stale Cache Fallback

When the circuit breaker is OPEN, EdgeWrap attempts to serve a stale cached response before returning a 503. The maximum age of the stale response is controlled by the staleIfErrorSec setting in your cache configuration (default: 3600 seconds).

OPEN state fallback logic

Circuit OPEN
  │
  ▼
Check cache database for stale response
  ├── Stale response found AND age < staleIfErrorSec  →  Serve stale cache (X-Cache-Status: STALE)
  └── No stale response found                         →  Return 503 Service Unavailable

Tip: Set staleIfErrorSec to a high value (e.g. 86400) on read-only public endpoints so clients get cached results instead of error pages during server outages.

Manual Reset via API

Force the circuit breaker back to CLOSED immediately after fixing origin server issues:

Reset circuit breaker state

curl -X POST https://server.edgewrap.pro/v1/projects/prj_abc123/circuit-breaker/reset \
  -H "Authorization: Bearer <your_session_token>"