Error Code Architecture

DSAR uses package-owned error catalogs with globally unique identifiers.

• Each package owns its catalog in src/types/error-codes.ts.
• @dsar/internals-error-codes is factory-only (createErrorRegistry, createErrorCodeSchema, and shared types).
• Docs coverage and ID uniqueness are validated by scripts/check-error-doc-coverage.mjs.

Namespace Registry

Backend Catalog

The canonical backend catalog is emitted by @dsar/backend from packages/backend/src/types/error-codes.ts.

Backend Envelope fields

All non-success responses include:

• error.id - stable backend error identifier (DSAR-BE-xxxx)
• error.code - semantic machine-readable code
• error.docsUrl - canonical documentation link for the identifier (https://dsar-sdk.dev/errors/dsar-be-xxxx)
• error.message - human-readable summary
• error.status - HTTP status
• error.trace - optional diagnostics-only payload (e.g. trace.lifecycle for transition errors)

Catalog

Logging behavior

toErrorResponse (in packages/backend/src/middleware/errors.ts) logs all mapped and unmapped errors server-side using structured logs including:

• id
• code
• status
• docsUrl
• request (method, path, query, sanitized headers, optional body preview)
• sanitized error payload (only name, message, code, and stack in development)

Header and query redaction

Sensitive headers (authorization, cookie, proxy-authorization, set-cookie, x-api-key) are replaced with [REDACTED] before logging.

Query parameters matching sensitive names (token, secret, password, api_key, apikey, auth, access_token, key) are also redacted.

Body preview limits

Request body previews use two related constants: BODY_PREVIEW_LIMIT (default 4096 bytes) is the maximum number of bytes included in the preview text, and BODY_PREVIEW_MAX_BYTES (BODY_PREVIEW_LIMIT + 1) is the stream read cap that reads one extra byte to detect whether the body was truncated. Bodies exceeding the limit are either:

• omitted with a descriptive message when content-length declares a size beyond BODY_PREVIEW_LIMIT, or
• truncated after streaming up to BODY_PREVIEW_MAX_BYTES with a truncated: true flag in the log payload.

Binary content types (application/octet-stream, multipart/form-data) are excluded entirely with [binary content omitted]. GET and HEAD requests skip body capture.