> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Health and readiness

> The liveness, readiness, and version probe contract exposed by every Lerian service — the `/health`, `/readyz`, and `/version` endpoints, their response shapes, startup and shutdown behavior, and per-service coverage.

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](#per-service-coverage) 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) |

<Note>
  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.
</Note>

## The `/readyz` response body

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

```json theme={null}
{
  "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`](/en/reference/byoc-configuration#deployment-mode-and-tls): `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](/en/reference/byoc-configuration#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](/en/reference/systemplane/overview).                                                          |
| 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). |

<Note>
  **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](/en/reference/default-network-ports). `Varies` marks a service whose default port depends on deployment configuration.
</Note>