Health and readiness

Reference the /health, /readyz, and /version probe contract exposed by every Lerian service, with response shapes and startup and shutdown behavior.

Most deployable Lerian services expose the same three operational HTTP endpoints on their main application port: /health, /readyz, and /version. Orchestrators such as Kubernetes use them to decide when a service is alive, when it can receive traffic, and which build it runs. This is the standard probe contract, not a guarantee for every service. Some components (workers and sidecars) expose only a subset. The per-service coverage table below is authoritative for exceptions.

The probe endpoints

Endpoint	Method	Purpose	Status	Auth
/health	GET	Liveness. Confirms the process is up. Returns 200 with body healthy.	200	Public (before auth)
/readyz	GET	Readiness. Confirms every dependency is reachable. Returns 200 when ready, 503 when any dependency is down or degraded.	200 / 503	Public (before auth)
/version	GET	Build info. Returns the running version and build metadata.	200	Public (before auth)

The spellings are exactly /health and /readyz, not /healthz or /livez. All three probes sit on the main application port, before the authentication middleware. They are public probes, and they stay out of access logs and request tracing.

The /readyz response body

/readyz returns a JSON document describing overall readiness and each dependency check.

{
  "status": "healthy",
  "checks": {
    "postgres": { "status": "up", "latency_ms": 2, "tls": true },
    "redis":    { "status": "skipped", "reason": "not configured" },
    "rabbitmq": { "status": "degraded", "breaker_state": "half-open", "latency_ms": 12 }
  },
  "version": "1.2.3",
  "deployment_mode": "byoc"
}

Field	Meaning
status	Overall readiness: healthy or unhealthy.
checks	One entry per dependency (Postgres, MongoDB, Redis, RabbitMQ, systemplane, and others).
checks.<dep>.status	Per-dependency result: up, down, degraded, skipped, or n/a.
checks.<dep>.latency_ms	Round-trip probe latency in milliseconds, when measured.
checks.<dep>.tls	Whether the connection to that dependency uses TLS.
checks.<dep>.breaker_state	Circuit-breaker state, when a breaker fronts the dependency.
checks.<dep>.error / .reason	Failure detail or the reason a check was skipped. Sanitized in saas and byoc; verbose in local.
version	Running service version.
deployment_mode	The active DEPLOYMENT_MODE: local, saas, or byoc.

Status vocabulary is a closed set:

• Overall status: healthy or unhealthy.
• Per-check status: up, down, degraded, skipped, n/a.

/readyz returns HTTP 200 only when overall status is healthy. If any check is down or degraded, it returns HTTP 503.

Startup and shutdown behavior

The probes prevent an orchestrator from routing traffic to a service that cannot serve it.

• Startup self-probe. /readyz returns 503 (“server not ready”) until the listener is up and dependencies are reachable. A load balancer therefore does not receive a starting pod prematurely, even if /health already answers 200.
• Graceful drain. On SIGTERM, the service flips /readyz to 503 for a drain window (about 12 seconds) while /health stays 200. Orchestrators stop routing new traffic during the window, then the process exits once in-flight work drains. The window is tunable via READYZ_DRAIN_DELAY_SEC (some services use READYZ_DRAIN_GRACE_SECONDS).
• Deployment mode. The /readyz body reports the active DEPLOYMENT_MODE. In saas mode, a dependency reached without TLS fails the readiness (and boot) check. In byoc, TLS is a recommendation, not a requirement.

Multi-tenant readiness

When you enable multi-tenancy, the service adds an auth-gated per-tenant readiness probe:

GET /readyz/tenant/{id}

It runs the readiness checks against a single tenant’s resolved connections. The global /readyz reports tenant-scoped checks as n/a and points to the per-tenant route.

Per-service coverage

Every service below exposes /health (liveness) and /readyz (readiness) on its main port. The table lists default ports, the multi-tenant probe where it applies, and the two path deviations.

Product / service	Main port	Liveness	Readiness	Multi-tenant readyz	Notes
Midaz ledger	3002	/health	/readyz	—	Also /version. No /metrics (OTLP push).
Tracer	4020	/health	/readyz	—	/version, /metrics. Optional reservation gRPC seam (off by default).
Reporter (API)	4005	/health	/readyz	—	/version. Runs when RUN_MODE=api.
Reporter (worker)	4006	/health	/readyz	—	Dedicated worker health server (RUN_MODE=worker).
Flowker (API)	4021	/health	/readyz	—	/metrics, /version.
Flowker (worker)	4022	/health	/readyz	—	Worker health port.
Flowker (XSD-validator sidecar)	8081	/health	—	—	Liveness only.
Matcher	4018	/health	/readyz	—	/version. Exposes the systemplane admin API.
Lender	8080	/health	/readyz	—	/version. Webhook receivers expose their own /health and /readyz. Systemplane admin API.
Access Manager	4000 (auth), 8000 (authorizer)	/health	/readyz	—	Two servers, each with its own probes.
Fees	4002	/health	/readyz	—	Part of Midaz; deployable independently.
Pix — Direct, via JD	8080	/health	/readyz	Yes	/metrics, /version. Systemplane admin API.
Pix — Indirect, via BTG	4014	/health	/readyz (+ /ready)	—	Deviation: the API additionally answers /ready alongside /readyz. Multi-component (API plus workers).
Pix switch	Varies (dedicated component)	/health	/readyz	—	Per adapter; systemplane runs as a separate deployable component.
TED — via JD	4027	/health, /health/live	/readyz, /health/ready	—	Deviation: additionally exposes /health/live and /health/ready. Systemplane admin API.
Boleto and bill payments — via BTG	8080	/health	/readyz	Yes	Multi-component.
CCS	4030 (HTTP), 7001 (gRPC)	/health	/readyz	Yes	/metrics, /version. Systemplane admin API.
STA	4028	/health	/readyz	Yes	/metrics, /version. Systemplane admin API.
SISBAJUD	4029	/health	/readyz	Yes	/metrics, /version. Systemplane admin API.
SLC	4111	/health	/readyz	Yes	/metrics, /version. Systemplane admin API.
SPI	8080	/health	/readyz	—	Systemplane admin API.
SPB	Varies	/health	/readyz	—	Systemplane admin API.
SILOC	Varies	/health	/readyz	—	—
Consignado	8080	/health	/readyz	Yes	/metrics, /version. Systemplane admin API.
SPB file exchange (BC Correios)	9090	/health (Live)	/readyz (Ready)	—	Deviation: /health maps to the liveness (Live) handler and /readyz to the readiness (Ready) handler. Systemplane admin API (catalog).

Multi-tenant readyz shows Yes where the service registers GET /readyz/tenant/{id}. The route appears when you enable multi-tenancy. A — means the service registers no dedicated per-tenant probe.

Ports are compose/.env.example defaults and can be overridden per deployment. See Default network ports. Varies marks a service whose default port depends on deployment configuration.