Understanding the Circuit Breaker

Setup

Via the UI

The toggle sits in the route wizard in Step 5 — Reliability (together with Retry and Request Mirroring). Uptime Monitoring is controlled in Step 4 — Access.

1. Create or edit a route
2. Enable Uptime Monitoring (prerequisite, Step 4)
3. In Step 5 enable the Circuit Breaker toggle
4. Set Threshold (default 5 consecutive failures)
5. Set Timeout (default 30 seconds)
6. Save

The route card shows a badge: CB: Closed (green), CB: Open (red), CB: Half-Open (amber).

Via the API

# Enable Circuit Breaker
curl -X PUT https://gatecontrol.example.com/api/v1/routes/1 \
  -H "Authorization: Bearer gc_..." \
  -H "Content-Type: application/json" \
  -d '{
    "monitoring_enabled": true,
    "circuit_breaker_enabled": true,
    "circuit_breaker_threshold": 5,
    "circuit_breaker_timeout": 30
  }'

# Manually reset the Circuit Breaker (since v1.50.4)
curl -X POST https://gatecontrol.example.com/api/v1/routes/1/circuit-breaker/reset \
  -H "Authorization: Bearer gc_..."

Important notes

• Monitoring is mandatory. Without Uptime Monitoring enabled, the Circuit Breaker has no data source and always stays in the closed state.
• Failure counter and open timestamp are persisted in the database (cb_failure_count, cb_opened_at). Open circuits survive restarts; if the timestamp is missing after a restart, it is re-set on the first check run.
• The Circuit Breaker operates per route, not per backend. For load balancing with multiple backends, the circuit opens when the monitoring target is unreachable.
• In the open state no requests are forwarded to the backend — Caddy responds with 503 Service Unavailable + Retry-After header. No bypass per API or individual request.
• Manual reset (since v1.50.4): POST /api/v1/routes/:id/circuit-breaker/reset or the Reset circuit breaker button in the route edit modal (only visible when status ≠ closed). Sets cb_failure_count = 0, cb_opened_at = NULL, status to closed, and re-renders the Caddy config immediately. Without this reset, an open breaker waits for the next monitoring cycle and runs through the normal open → half-open → closed path.
• Circuit Breaker is only available for HTTP routes, not for L4 (TCP/UDP).

See also

• RETRY-ON-ERROR.md — Retries within the closed state
• UPTIME-MONITORING.md — Data source for the state machine
• concepts/routing.md — Placement in the request flow