Health and readiness

Reference the /health, /readyz, and /version probes, with response shapes and per-service coverage.

This page describes the health-port contract used by releases that adopt it. Earlier releases can use different paths, ports, and response bodies. See per-service coverage.

​

The probe endpoints

Endpoint	Port	Purpose
/health	Health	Liveness. Returns text healthy or unhealthy; a failed Live check returns HTTP 503.
/readyz	Health	Readiness. Returns the checks and the service version as JSON.
/version	Main	Returns the service version.
/health	Main	Returns a constant successful response.
/metrics	Health	Exposes health metrics for Prometheus.

Set HEALTH_PORT to enable the health listener. If it is unset, the listener does not start. Charts and examples configure 8099; the library does not select a port. Keep the health port internal and off public Ingress and load balancers. Main API ports do not change.

Some multi-tenant services expose /readyz/tenant/:id on the health port. This unauthenticated, on-demand check does not change pod readiness.

​

The /readyz response body

The following body applies to releases using the current shared health contract. Registered checks vary by service. A check that is not configured has no entry.

{
  "status": "healthy",
  "checks": {
    "postgres": { "status": "up", "gating": false, "latency_ms": 2 }
  },
  "version": "1.2.3"
}

Field	Meaning
status	Overall result: healthy, degraded, or unhealthy.
checks	Registered checks and their results.
checks.<dep>.status	Check result: up, down, or degraded.
checks.<dep>.gating	Whether the check gates readiness.
checks.<dep>.latency_ms	Probe latency in milliseconds, when measured.
checks.<dep>.error	A stable error class from a closed set, when present; never the raw dependency error message.
version	Running service version.

Readiness returns HTTP 503 until every Startup check passes for the first time. After that, a shared dependency failure reports degraded with HTTP 200. Liveness can return 503 for a failed Live check.

The shared health metrics are health_ready and health_check_status{check,mode,status}. They are separate from OTLP telemetry.

​

Per-service coverage

Check the product version before you change probes. Availability in a release does not mean that your deployment already uses it.

Product / service	Release	Health-port coverage
Midaz	v4.4.1	Uses the main-port probes below.
Tracer	Current	Uses the health port. Of the probes, the main port keeps only /health and /version. Readiness stays 503 until a license is accepted.
Matcher	v6.3.0	Uses the health port.
Reporter	v4.9.0	Uses the health port. Readiness stays 503 until a license is accepted. The API port opens only after that.
Lender	v4.2.0	Uses the health port. Of the probes, the main port keeps only /health and /version. Readiness stays 503 until a license is accepted.
Streaming Hub	v3.4.0	Uses the health port. Of the probes, the main port keeps only /health and /version, and it also serves /runtime. Readiness stays 503 until a license is accepted.
Access Manager	v3.20.0	Uses the health port. Readiness stays 503 until a license is accepted.
Pix (Direct, via JD)	v1.6.1	Uses the health port.
Pix (Indirect, via BTG)	v1.15.0	Uses the health port. Readiness stays 503 until a license is accepted.
Pix Lerian	v1.3.0	Uses the health port on every component. The main port also answers /readyz under the route prefix.
TED Lerian	Current	Uses the health port. Of the probes, the main port keeps only /health and /version.
Consignado	v4.5.0	Uses the health port. Of the probes, the main port keeps only /health and /version. /readyz reports the streaming check, and a down broker does not return 503. Readiness stays 503 until a license is accepted.
Boleto and bill payments (via BTG)	v1.3.0	Uses the health port. Readiness stays 503 until a license is accepted.
Plugin SISBAJUD	v1.3.0	Uses the health port. Of the probes, the main port keeps only /health and /version. Readiness stays 503 until the boot, PostgreSQL, and license checks pass. With the Mensageria over the webhook transport, it also waits for the webhook listener.

The table below lists the main-port probes of the services that do not use the health port, and each service keeps its own contract.

Product / service	Main port	Liveness	Readiness	Notes
Midaz ledger	3002	/health	/readyz	Also /version. No /metrics (OTLP push).
Console	8081	/api/admin/health/alive	/api/admin/health/readyz	Deviation: probes live under /api/admin/health/. Readiness answers 503 until a license is accepted. MongoDB is reported and does not gate readiness.
TED (via JD)	8080	/health, /health/live	/readyz, /health/ready	Deviation: additionally exposes /health/live and /health/ready. Systemplane admin API.
CCS	4030	/health	/readyz	/metrics, /version.
STA	4028	/health	/readyz	/metrics, /version. Systemplane admin API.
SISBAJUD Mensageria	4031	/health	/readyz	/version. Systemplane admin API. The execution API listens on its own TLS port, 4032.
SLC	4111	/health	/readyz	/metrics, /version. Systemplane admin API.
SPI	8080	/health	/readyz	Systemplane admin API.
SPB	3000	/health	/readyz	Systemplane admin API.
SILOC	9820	/health	/readyz	—
Flowker	4021	/health	/readyz	/version. The worker answers /health, /readyz and /version on 4022.
JD Courier	8080	/health	/readyz	/version. Systemplane admin API when enabled.
BC Correios	8080	/health	/readyz	/version.
SCR	3003	/health	/readyz	/version. Systemplane admin API.
SRC	3006	/health	/readyz	/version. Systemplane admin API.

Ports are default values and can be overridden per deployment. See Default network ports.