- 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-agnosticErrorCode, optional non-sensitivedetailsand acausechain. Non-QuantLayerErrorexceptions at a boundary are defects and reported asINTERNAL. - HTTP mapping exists only in
apps/apiand is exhaustive by type; the response shape is{ error: { code, message, requestId } }; 5xx messages are generic. - Logging uses pino via
createLoggerfrom@quantlayer-protocol/runtime: JSON to stdout, ISO time,servicefield, default redaction of sensitive keys.consoleis banned by lint. - The API uses
nestjs-pinofor 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.