0006. Error model and structured logging

Design document, published from the repository at docs/adr/0006-errors-and-logging.md.

  • Status: Accepted
  • Date: 2026-11-13

Context

Operators need machine-readable logs and correlated errors. Clients need stable error codes. Neither may receive secrets or internal details.

Decision

  • One error class, QuantLayerError, with a transport-agnostic ErrorCode, optional non-sensitive details and a cause chain. Non-QuantLayerError exceptions at a boundary are defects and reported as INTERNAL.
  • HTTP mapping exists only in apps/api and is exhaustive by type; the response shape is { error: { code, message, requestId } }; 5xx messages are generic.
  • Logging uses pino via createLogger from @quantlayer-protocol/runtime: JSON to stdout, ISO time, service field, default redaction of sensitive keys. console is banned by lint.
  • The API uses nestjs-pino for request logs and request-id propagation.

Consequences

Logs can be shipped without parsing free text. Adding a new ErrorCode forces the HTTP mapping to be updated at compile time.