Health and readiness

Most deployable Lerian services expose the same three operational HTTP endpoints — /health, /readyz, and /version — on their main application port. Orchestrators such as Kubernetes use them to decide when a service is alive, when it can receive traffic, and which build is running. 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 are registered on the main application port, before the authentication middleware (they are public probes), and are excluded from 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 are wired so an orchestrator never routes 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 — so a starting pod is not added to a load balancer 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 active DEPLOYMENT_MODE is echoed in the /readyz body. In saas mode, a dependency reached without TLS fails the readiness (and boot) check; in byoc it is recommended but not enforced.

Multi-tenant readiness

When multi-tenancy is enabled, 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.
Fetcher (manager)	4006	`/health`	`/readyz`	Yes	`/metrics`.
Fetcher (worker)	4007	`/health`	`/readyz`	Yes	`/metrics`. Dedicated worker health server.
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 is marked Yes where the service registers GET /readyz/tenant/{id}; it appears when multi-tenancy is enabled. A — means no dedicated per-tenant probe is registered for that service.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.

Overview

Integration essentials

Stability & quality

Health and readiness

The probe endpoints

The `/readyz` response body

Startup and shutdown behavior

Multi-tenant readiness

Per-service coverage

​The probe endpoints

​The /readyz response body

​Startup and shutdown behavior

​Multi-tenant readiness

​Per-service coverage

The probe endpoints

The `/readyz` response body

Startup and shutdown behavior

Multi-tenant readiness

Per-service coverage