Telemetry and Status · Developer Docs

Request IDs

Every response carries an X-Request-Id header. The value is a UUID generated by the platform's middleware on entry. Log it. Quote it when reporting issues — every internal log line ties back to it.

If you submit your own correlation ID via X-Correlation-Id, the platform echoes it back unchanged in addition to its own request ID.

Error envelope

Every JSON error response has the same shape:

{
  "success": false,
  "error": {
    "code": "STABLE_STRING",
    "message": "A human-readable description.",
    "details": { /* optional, present for 400s and 422s */ }
  }
}

error.code is stable. Switch on it.
error.message is for humans. Do not parse it.
error.details carries Zod field-error trees on 400/422, and contextual hints on others.

HTTP status table

Status	Meaning	Action
`200`	Success	—
`201`	Created (POST that creates a resource)	—
`204`	Success, no body (e.g. successful DELETE)	—
`400`	Malformed request	Fix the payload; do not retry as-is
`401`	Missing / invalid / revoked token	Refresh credentials
`403`	Authenticated but not entitled	Confirm scope; do not retry
`404`	Not found, or hidden from this caller	—
`409`	State conflict (e.g. double-accept of a Hold)	Re-read current state and decide
`422`	Validation failed	See `error.details`
`429`	Rate-limited	Honour `Retry-After`; see Auth and Rate Limits
`500`	Unexpected server error	Retry with backoff, then escalate with `X-Request-Id`
`502`/`503`/`504`	Upstream / dependency issue	Retry with backoff

Health endpoints

The three health endpoints described in Public Endpoints are the canonical signals for operations:

/api/health/live — process is responsive (poll every 30–60s)
/api/health/ready — dependencies are reachable (poll every 60–120s)
/api/health — combined envelope, suitable for a load-balancer probe

Health endpoints are observability signals, not feature contracts. Do not gate user-facing logic on their response shape — it may change without notice.

What we will not expose

The full route table to the public (probe it and you get a polite 404)
Internal operations dashboards (auth-gated under /dashboard/system and admin surfaces)
Database schema reflection endpoints (there are none)

Where to next

Quickstart — the first call
Auth and Rate Limits — bearer scheme