Errors and health

Exported from errors.ts and health.ts.

Error responses — ErrorPayloadSchema

Every non-2xx response from the API uses this shape:

import { ErrorPayloadSchema, type ErrorPayload } from '@klappay/types'

const payload: ErrorPayload = {
  error: {
    code: 'validation_error',
    message: 'amount must be positive',
    param: 'amount',
  },
}

• code — a stable, machine-readable identifier (e.g. validation_error, charge_not_found, invalid_trigger_state). Safe to branch on in code. There's no single enum of every possible value here (it's a plain string, since the set is per-endpoint) — the live OpenAPI/Scalar reference is the authoritative source for which codes a specific endpoint can return: every response in its responses block names the actual code(s) in parentheses at the end of the description.
• message — human-readable, safe to log or show a developer. Not meant for end users verbatim.
• param — which request field the error refers to, when applicable (omitted for errors that aren't about a specific field).

If you want a typed exception thrown automatically instead of parsing this shape yourself, an official SDK does that — available at github.com/klappay; see the live API reference for details on the full list of error classes.

GET /v1/health — HealthSchema

HealthSchema/Health is the response shape of the public health-check endpoint. status/the HTTP status code both mirror db: error (and 503) when the database connectivity check fails, so a plain status-code-only uptime check still catches a DB outage without needing to inspect the JSON body.

The other fields are operational signals, not just "is the process alive": pendingWebhooks (deliveries still awaiting a successful attempt), oldestPendingChargeAgeSeconds (age of the oldest still-unpaid charge, null if none), and lastContractWatcherEventAgeSeconds (seconds since the last on-chain payment notification was received — a cheap proxy for "is payment detection still working", null if none have ever arrived).