← Docs

Recipe: Health / readiness / liveness endpoint design

A single GET /health that orchestrators, load balancers, and monitoring tools can trust.

Contract

GET /health HTTP/1.1
Host: api.getnimbus.net

200 OK
Content-Type: application/json

{
  "status": "pass",
  "version": "1.0.0",
  "uptime": 84722,
  "checks": {
    "db": "pass",
    "redis": "pass",
    "license": "pass"
  }
}

Semantics

  • Liveness — returns 200 if the process is alive. No dependency checks.
  • Readiness — fails (503) when critical dependencies are unavailable.
  • Health — composite view. Aggregate status is pass, warn, or fail.

Implementation notes

Each check runs with a 2-second timeout. Failures are cached for 10 seconds to avoid thundering-herd retries against degraded backends.

The endpoint is excluded from rate-limiting and auth middleware. Response body stays under 4 KB so cloud LBs parse it without buffering.

Expose /health/live and /health/ready as separate routes if your orchestrator distinguishes them.

← Back to docs