Errors & problem+json

DaloyJS errors are first-class. Every thrown HttpError serializes to RFC 9457 problem+json with a stable type URI, a request-id, and the appropriate Content-Type.

From thrown error to problem+json

01handlerthrow new NotFoundError(...)any HttpError subclass
02frameworkMap to RFC 9457 fieldstype · title · status · detail
03productionRedact 5xx detailNODE_ENV=production strips internals
04wireSerialized responseapplication/problem+json + x-request-id

A thrown HttpError becomes a problem+json document automatically. In production the detail field on 5xx responses is redacted so stack traces and SQL fragments never reach the client, while the full error still goes to your onError hook.

Built-in error classes

import {
  BadRequestError,                   // 400
  UnauthorizedError,                 // 401
  ForbiddenError,                    // 403
  NotFoundError,                     // 404
  MethodNotAllowedError,             // 405 + Allow header
  RequestTimeoutError,               // 408
  ConflictError,                     // 409 + cache-control: no-store
  PayloadTooLargeError,              // 413
  UnsupportedMediaTypeError,         // 415
  ValidationError,                   // 422
  TooManyRequestsError,              // 429 + Retry-After
  RequestHeaderFieldsTooLargeError,  // 431
  InternalError,                     // 500 (detail redacted in production)
} from "@daloyjs/core";

Throwing in a handler

import { NotFoundError } from "@daloyjs/core";

app.route({
  method: "GET",
  path: "/users/:id",
  operationId: "getUser",
  responses: { 200: { description: "ok" }, 404: { description: "missing" } },
  handler: async ({ params }) => {
    const user = await db.find(params.id);
    if (!user) throw new NotFoundError(`user ${params.id} not found`);
    return { status: 200, body: user };
  },
});

Wire format

The request id is returned to the client in two places: the x-request-id response header, and (per RFC 9457 §3.1) the problem document's instance field as a urn:request:<uuid> URN. There is no top-level requestId property, clients should read the header or parse the URN from instance.

json

HTTP/1.1 404 Not Found
content-type: application/problem+json
x-request-id: c9aa8e1c-7a6e-4f1e-9f44-c2e5d2c4a431

{
  "type": "https://daloyjs.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "user 42 not found",
  "instance": "urn:request:c9aa8e1c-7a6e-4f1e-9f44-c2e5d2c4a431"
}

Production redaction

When NODE_ENV=production, DaloyJS strips the detail field on any 5xx response so internal stack traces and SQL fragments don't leak to clients. The full error is still emitted to your logger via the onError hook.

Custom error classes

import { HttpError } from "@daloyjs/core";

export class QuotaExceededError extends HttpError {
  constructor(resource: string) {
    super(429, {
      title: "Quota exceeded",
      type: "https://api.example.com/errors/quota-exceeded",
      detail: `Quota exceeded for ${resource}`,
    });
  }
}

Custom `onError`

app.use({
  onError: async (error, ctx) => {
    logger.error({ err: error, requestId: ctx?.requestId }, "request failed");
    // return a Response to override; otherwise DaloyJS serializes problem+json
  },
});

Search docs