Skip to main content

​
GET /health

Returns the health status of all configured backends. This endpoint does not require authentication and can be used for monitoring, alerting, and load balancer health checks.

​
Request

No parameters required. 
GET /health

​
Response

Returns a JSON object with overall status and per-backend health details.
​
overall_status
string
Overall router health status:
  • "healthy": At least one backend is healthy
  • "unhealthy": All backends are unhealthy
​
backends
array
Array of backend health status objects

​
Health Check Algorithm

Backends are marked healthy/unhealthy based on a circuit breaker pattern:
  1. Initial State: All backends start healthy
  2. Health Probe: Background task calls configured RPC method (e.g., getSlot) every health_check.interval_secs (default 30s)
  3. Failure Threshold: Backend marked unhealthy after consecutive_failures_threshold consecutive failures (default 3)
  4. Recovery Threshold: Unhealthy backend marked healthy after consecutive_successes_threshold consecutive successes (default 2)

​
Configuration

Health check behavior is configured in config.toml: 
[health_check]
interval_secs = 30                    # Check frequency
timeout_secs = 5                      # Per-check timeout
method = "getSlot"                    # RPC method to call
consecutive_failures_threshold = 3    # Failures before unhealthy
consecutive_successes_threshold = 2   # Successes before healthy

​
Example Request

Health Check
curl https://rpc.example.com/health

​
Response Examples

{
  "overall_status": "healthy",
  "backends": [
    {
      "label": "mainnet-primary",
      "healthy": true,
      "last_check": "SystemTime { tv_sec: 1709467234, tv_nsec: 123456789 }",
      "consecutive_failures": 0,
      "consecutive_successes": 15,
      "last_error": null
    },
    {
      "label": "backup-rpc",
      "healthy": true,
      "last_check": "SystemTime { tv_sec: 1709467234, tv_nsec: 987654321 }",
      "consecutive_failures": 0,
      "consecutive_successes": 15,
      "last_error": null
    }
  ]
}

​
Use Cases

​
Monitoring & Alerting

Monitor overall_status and backend-level healthy flags:
Alert on Unhealthy
if [ $(curl -s https://rpc.example.com/health | jq -r '.overall_status') == "unhealthy" ]; then
  echo "CRITICAL: All RPC backends are down!"
fi

​
Load Balancer Health Checks

Configure upstream health checks to poll /health and validate overall_status:
nginx.conf
upstream rpc_router {
  server rpc.example.com:28899;
  
  # Health check (requires nginx-plus or lua module)
  check interval=10000 rise=2 fall=3 timeout=5000 type=http;
  check_http_send "GET /health HTTP/1.1\r\nHost: rpc.example.com\r\n\r\n";
  check_http_expect_alive http_2xx;
}

​
Grafana Dashboard

Parse health endpoint in a JSON datasource:
  • Panel 1: Gauge showing healthy backend count
  • Panel 2: Table with label, healthy, consecutive_failures, last_error
  • Alert: Trigger when overall_status != "healthy"

​
Impact on Request Routing

Unhealthy backends are automatically excluded from:
  • Weighted load balancing selection
  • Method-based routing (falls back to weighted selection if target is unhealthy)
  • WebSocket backend selection
If all backends are unhealthy, proxy requests return 503 Service Unavailable.

​
Hot Reload Support

The health state persists across configuration reloads (kill -HUP <pid>). When backends are reloaded:
  • Existing backend labels retain their health status and history
  • New backends start healthy with no history
  • Removed backends are discarded from the health state

Build docs developers (and LLMs) love

Get started for freeTalk to us