Creating Custom Error Classes

Welcome to the final lesson of Request Validation and Express Error Architecture! Your API already validates input with Zod, creates request context for every request, and applies JSON requirements only to routes that consume bodies. Now you’ll bring those pieces together under one predictable error architecture. You’ll create a reusable AppError, add route-specific 405 Method Not Allowed handling, and expand the final Express error middleware so it safely maps application, validation, parser, PostgreSQL, and unexpected failures. You’ll also preserve an important distinction between a matched resource that does not exist and an application path that matched no route at all. Previously, request context established requestId and startedAt before feature routes ran. Zod errors already reached the final middleware, and Express 5 automatically forwarded rejected asynchronous handlers. This lesson completes that pipeline so routes can describe failures by throwing errors while one final middleware owns the client response format.

Understanding the Final Error Flow

A successful request still returns its normal resource representation: text Request ↓ Global middleware ↓ Validation ↓ Route handler ↓ Repository ↓ Ticket, comment, array, or 204 response A failure follows a shared path: text Request ↓ Middleware or route throws/delegates an error ↓ Express error flow ↓ Final errorHandler ↓ Consistent HTTP error response with request metadata Several different failures can enter this pipeline: text AppError ZodError Malformed JSON PostgreSQL foreign-key violation PostgreSQL uniqueness violation Unexpected runtime failure The final middleware recognizes each known category in a deliberate order. Specific failures are mapped first, while the generic 500 response remains the last fallback.

Why Routes Should Not Format Every Error

Earlier route handlers sometimes wrote an error response directly: TypeScriptif (!ticket) { response.status(404).json({ error: { code: "TICKET_NOT_FOUND", message: "Ticket not found.", }, }); return; } This works, but repeating the same formatting across many handlers has drawbacks: Error envelopes can drift between routes. Request metadata must be added repeatedly. New error categories require changes in many files. Route handlers become crowded with response-formatting details. The completed design allows the route to describe the failure instead: TypeScriptif (!ticket) { throw new AppError( 404, "TICKET_NOT_FOUND", "Ticket not found.", ); } Express 5 forwards the thrown error to the final error middleware. The route decides what went wrong, while the centralized handler decides how errors are represented to clients.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

The reusable error class lives in src/lib/errors.ts. It extends JavaScript’s built-in Error while adding the HTTP and API fields required by the application.

TypeScript

export class AppError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly code: string,
    message: string,
    public readonly details?: unknown,
  ) {
    super(message);
    this.name = "AppError";
  }
}

export class AppError extends Error {
  constructor(
    public readonly statusCode: number,
    public readonly code: string,
    message: string,
    public readonly details?: unknown,
  ) {
    super(message);
    this.name = "AppError";
  }
}

Extending Error means AppError behaves like a normal JavaScript exception. It can be thrown, passed to next(error), inspected with instanceof, and forwarded through Express’s error pipeline.
statusCode stores the HTTP status the final middleware should send. Examples include 400, 404, 405, and 415.
code is a stable machine-readable identifier such as TICKET_NOT_FOUND or METHOD_NOT_ALLOWED. Client applications can branch on this value without depending on the human-readable message.
message is handled by the parent Error class. It gives developers and API clients a readable explanation of the failure.
details is optional and can include safe structured context. For example, a method error can list the methods allowed by the matched route.
Setting this.name to "AppError" keeps the error recognizable during logging and debugging while preserving normal error behavior.

A route can now create a focused failure with one expression:

TypeScript

throw new AppError(
  400,
  "INVALID_REQUESTER",
  "requesterId does not reference an existing user.",
);

throw new AppError(
  400,
  "INVALID_REQUESTER",
  "requesterId does not reference an existing user.",
);

A request can reach a valid route path while using an unsupported HTTP method.

Consider the ticket collection:

text

GET  /api/tickets
POST /api/tickets

GET  /api/tickets
POST /api/tickets

The path exists, but methods such as PUT and DELETE are not supported there. That situation should return 405 Method Not Allowed, not the broader 404 Not Found.

The reusable middleware lives in src/middleware/method-not-allowed.ts.

TypeScript

import type { RequestHandler } from "express";

import { AppError } from "../lib/errors.js";

export const methodNotAllowed =
  (allowedMethods: string[]): RequestHandler =>
  (request, response, next) => {
    response.setHeader(
      "Allow",
      allowedMethods.join(", "),
    );

    next(
      new AppError(
        405,
        "METHOD_NOT_ALLOWED",
        `${request.method} is not allowed for this route.`,
        { allowedMethods },
      ),
    );
  };

import type { RequestHandler } from "express";

import { AppError } from "../lib/errors.js";

export const methodNotAllowed =
  (allowedMethods: string[]): RequestHandler =>
  (request, response, next) => {
    response.setHeader(
      "Allow",
      allowedMethods.join(", "),
    );

    next(
      new AppError(
        405,
        "METHOD_NOT_ALLOWED",
        `${request.method} is not allowed for this route.`,
        { allowedMethods },
      ),
    );
  };

methodNotAllowed() is a middleware factory. Each route supplies its own list of supported methods when configuring the fallback.
The Allow response header communicates the methods accepted by that resource. For ["GET", "POST"], the header becomes Allow: GET, POST.
The attempted method is included in the error message. A PUT request therefore produces a message such as "PUT is not allowed for this route."
allowedMethods is also stored in details, giving clients a structured version of the same information.
The middleware does not write the JSON response itself. It creates an AppError and delegates it through next(error) so the final handler remains the only error formatter.

methodNotAllowed() is ordinary synchronous middleware. It deliberately transfers control into Express’s error pipeline:

TypeScript

next(
  new AppError(
    405,
    "METHOD_NOT_ALLOWED",
    `${request.method} is not allowed for this route.`,
    { allowedMethods },
  ),
);

next(
  new AppError(
    405,
    "METHOD_NOT_ALLOWED",
    `${request.method} is not allowed for this route.`,
    { allowedMethods },
  ),
);

Calling next() with no argument continues through normal route middleware. Calling next(error) skips the remaining normal handlers and searches for error middleware.

This is different from an async route that throws:

TypeScript

async (_request, response) => {
  const ticket = await findTicketById("tkt_missing");

  if (!ticket) {
    throw new AppError(
      404,
      "TICKET_NOT_FOUND",
      "Ticket not found.",
    );
  }

  response.status(200).json(ticket);
}

async (_request, response) => {
  const ticket = await findTicketById("tkt_missing");

  if (!ticket) {
    throw new AppError(
      404,
      "TICKET_NOT_FOUND",
      "Ticket not found.",
    );
  }

  response.status(200).json(ticket);
}

Because the handler is asynchronous, the thrown error rejects its returned promise. Express 5 automatically forwards that rejection to the final error middleware.

The ticket collection is grouped with router.route("/") in src/routes/ticket-routes.ts.

TypeScript

ticketRoutes.route("/")
  .get(
    validateRequest({
      query: ticketListQuerySchema,
    }),
    async (_request, response) => {
      const { query } =
        response.locals.validated as {
          query: TicketListQuery;
        };

      const result = await listTickets(query);

      response.setHeader(
        "X-Total-Count",
        String(result.total),
      );
      response.status(200).json(result.items);
    },
  )
  .post(
    requireJson,
    validateRequest({
      body: createTicketBodySchema,
    }),
    async (_request, response) => {
      const { body } =
        response.locals.validated as {
          body: CreateTicketBody;
        };

      if (!(await userExists(body.requesterId))) {
        throw new AppError(
          400,
          "INVALID_REQUESTER",
          "requesterId does not reference an existing user.",
        );
      }

      const ticket = await createTicket(body);

      response.setHeader(
        "Location",
        `/api/tickets/${ticket.id}`,
      );
      response.status(201).json(ticket);
    },
  )
  .all(methodNotAllowed(["GET", "POST"]));

ticketRoutes.route("/")
  .get(
    validateRequest({
      query: ticketListQuerySchema,
    }),
    async (_request, response) => {
      const { query } =
        response.locals.validated as {
          query: TicketListQuery;
        };

      const result = await listTickets(query);

      response.setHeader(
        "X-Total-Count",
        String(result.total),
      );
      response.status(200).json(result.items);
    },
  )
  .post(
    requireJson,
    validateRequest({
      body: createTicketBodySchema,
    }),
    async (_request, response) => {
      const { body } =
        response.locals.validated as {
          body: CreateTicketBody;
        };

      if (!(await userExists(body.requesterId))) {
        throw new AppError(
          400,
          "INVALID_REQUESTER",
          "requesterId does not reference an existing user.",
        );
      }

      const ticket = await createTicket(body);

      response.setHeader(
        "Location",
        `/api/tickets/${ticket.id}`,
      );
      response.status(201).json(ticket);
    },
  )
  .all(methodNotAllowed(["GET", "POST"]));

.get() and .post() preserve the existing successful collection behavior. Filtering still returns the ticket array and X-Total-Count, while creation still returns 201 and a Location header.
A missing requester is now represented by throwing AppError. Express 5 forwards it because the route handler is asynchronous.
.all() is placed after the supported methods. It catches any other method that reaches the same path.
The fallback advertises exactly GET and POST. It does not guess which methods are supported; the route configuration provides the authoritative list.

The static statistics route remains before the dynamic ticket route:

TypeScript

ticketRoutes.get(
  "/stats",
  async (_request, response) => {
    response.status(200).json(
      await countTicketsByStatus(),
    );
  },
);

ticketRoutes.get(
  "/stats",
  async (_request, response) => {
    response.status(200).json(
      await countTicketsByStatus(),
    );
  },
);

This ordering remains important. If /:ticketId came first, Express could treat stats as a ticket ID before reaching the intended handler.

Custom errors improve failure handling, but they do not replace correct route specificity and declaration order.

The detail route supports GET, PATCH, and DELETE.

TypeScript

ticketRoutes.route("/:ticketId")
  .get(
    validateRequest({
      params: ticketIdParamsSchema,
    }),
    async (_request, response) => {
      const { params } =
        response.locals.validated as {
          params: TicketIdParams;
        };

      const ticket =
        await findTicketById(params.ticketId);

      if (!ticket) {
        throw new AppError(
          404,
          "TICKET_NOT_FOUND",
          "Ticket not found.",
        );
      }

      response.status(200).json(ticket);
    },
  )

ticketRoutes.route("/:ticketId")
  .get(
    validateRequest({
      params: ticketIdParamsSchema,
    }),
    async (_request, response) => {
      const { params } =
        response.locals.validated as {
          params: TicketIdParams;
        };

      const ticket =
        await findTicketById(params.ticketId);

      if (!ticket) {
        throw new AppError(
          404,
          "TICKET_NOT_FOUND",
          "Ticket not found.",
        );
      }

      response.status(200).json(ticket);
    },
  )

Zod first validates the route-parameter format. A malformed identifier such as not-a-ticket becomes 400 VALIDATION_ERROR.
A structurally valid identifier such as tkt_missing reaches the repository. When no row exists, the handler throws TICKET_NOT_FOUND.
This preserves the distinction between malformed input and a validly shaped resource that is absent.

The update route uses the same application error when the repository cannot find a row.

TypeScript

.patch(
  requireJson,
  validateRequest({
    params: ticketIdParamsSchema,
    body: updateTicketBodySchema,
  }),
  async (_request, response) => {
    const { params, body } =
      response.locals.validated as {
        params: TicketIdParams;
        body: UpdateTicketBody;
      };

    const ticket = await updateTicket(
      params.ticketId,
      body,
    );

    if (!ticket) {
      throw new AppError(
        404,
        "TICKET_NOT_FOUND",
        "Ticket not found.",
      );
    }

    response.status(200).json(ticket);
  },
)

.patch(
  requireJson,
  validateRequest({
    params: ticketIdParamsSchema,
    body: updateTicketBodySchema,
  }),
  async (_request, response) => {
    const { params, body } =
      response.locals.validated as {
        params: TicketIdParams;
        body: UpdateTicketBody;
      };

    const ticket = await updateTicket(
      params.ticketId,
      body,
    );

    if (!ticket) {
      throw new AppError(
        404,
        "TICKET_NOT_FOUND",
        "Ticket not found.",
      );
    }

    response.status(200).json(ticket);
  },
)

requireJson still runs before Zod body validation.
A text request produces 415, malformed JSON produces 400 INVALID_JSON, and a valid JSON body with invalid fields produces 400 VALIDATION_ERROR.
Only after those input boundaries pass does the repository update run.

Deletion follows the same route-level pattern.

TypeScript

.delete(
  validateRequest({
    params: ticketIdParamsSchema,
  }),
  async (_request, response) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    if (!(await deleteTicket(params.ticketId))) {
      throw new AppError(
        404,
        "TICKET_NOT_FOUND",
        "Ticket not found.",
      );
    }

    response.status(204).send();
  },
)
.all(
  methodNotAllowed([
    "GET",
    "PATCH",
    "DELETE",
  ]),
);

.delete(
  validateRequest({
    params: ticketIdParamsSchema,
  }),
  async (_request, response) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    if (!(await deleteTicket(params.ticketId))) {
      throw new AppError(
        404,
        "TICKET_NOT_FOUND",
        "Ticket not found.",
      );
    }

    response.status(204).send();
  },
)
.all(
  methodNotAllowed([
    "GET",
    "PATCH",
    "DELETE",
  ]),
);

A successful deletion keeps its exact 204 No Content behavior.
A missing ticket throws an application error instead of formatting JSON locally.
Unsupported methods such as POST /api/tickets/tkt_1001 reach the .all() fallback and return 405 with Allow: GET, PATCH, DELETE.

The nested comment router supports only GET and POST.

TypeScript

commentRoutes.route("/")
  .get(async (_request, response) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    response.status(200).json(
      await listComments(params.ticketId),
    );
  })
  .post(
    requireJson,
    validateRequest({
      body: createCommentBodySchema,
    }),
    async (_request, response) => {
      const { params, body } =
        response.locals.validated as {
          params: TicketIdParams;
          body: CreateCommentBody;
        };

      if (!(await userExists(body.authorId))) {
        throw new AppError(
          400,
          "INVALID_AUTHOR",
          "authorId does not reference an existing user.",
        );
      }

      response.status(201).json(
        await createComment(
          params.ticketId,
          body.authorId,
          body.message,
        ),
      );
    },
  )
  .all(
    methodNotAllowed(["GET", "POST"]),
  );

commentRoutes.route("/")
  .get(async (_request, response) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    response.status(200).json(
      await listComments(params.ticketId),
    );
  })
  .post(
    requireJson,
    validateRequest({
      body: createCommentBodySchema,
    }),
    async (_request, response) => {
      const { params, body } =
        response.locals.validated as {
          params: TicketIdParams;
          body: CreateCommentBody;
        };

      if (!(await userExists(body.authorId))) {
        throw new AppError(
          400,
          "INVALID_AUTHOR",
          "authorId does not reference an existing user.",
        );
      }

      response.status(201).json(
        await createComment(
          params.ticketId,
          body.authorId,
          body.message,
        ),
      );
    },
  )
  .all(
    methodNotAllowed(["GET", "POST"]),
  );

The child router continues receiving validated parent parameters through response.locals.validated.
Missing authors now become thrown AppError instances.
A method such as DELETE /api/tickets/tkt_1001/comments reaches the nested .all() fallback and returns 405.
The Allow header reports only the methods implemented by this child collection.

The parent ticket router verifies that the ticket exists before entering the child comment router.

TypeScript

ticketRoutes.use(
  "/:ticketId/comments",
  validateRequest({
    params: ticketIdParamsSchema,
  }),
  async (_request, response, next) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    if (!(await findTicketById(params.ticketId))) {
      throw new AppError(
        404,
        "TICKET_NOT_FOUND",
        "Ticket not found.",
      );
    }

    next();
  },
  commentRoutes,
);

ticketRoutes.use(
  "/:ticketId/comments",
  validateRequest({
    params: ticketIdParamsSchema,
  }),
  async (_request, response, next) => {
    const { params } =
      response.locals.validated as {
        params: TicketIdParams;
      };

    if (!(await findTicketById(params.ticketId))) {
      throw new AppError(
        404,
        "TICKET_NOT_FOUND",
        "Ticket not found.",
      );
    }

    next();
  },
  commentRoutes,
);

The parent parameter is validated before the repository lookup.
A missing ticket throws AppError, preventing the child repository from listing or creating comments for an absent parent.
When the ticket exists, next() hands the request to commentRoutes.
Because this middleware is async, Express 5 automatically forwards a thrown AppError to the final error handler.

The media-type guard in src/middleware/require-json.ts now delegates an application error instead of formatting its own JSON response.

TypeScript

import type { RequestHandler } from "express";

import { AppError } from "../lib/errors.js";

export const requireJson: RequestHandler = (
  request,
  _response,
  next,
) => {
  if (!request.is("application/json")) {
    next(
      new AppError(
        415,
        "UNSUPPORTED_MEDIA_TYPE",
        "Content-Type must be application/json.",
      ),
    );
    return;
  }

  next();
};

import type { RequestHandler } from "express";

import { AppError } from "../lib/errors.js";

export const requireJson: RequestHandler = (
  request,
  _response,
  next,
) => {
  if (!request.is("application/json")) {
    next(
      new AppError(
        415,
        "UNSUPPORTED_MEDIA_TYPE",
        "Content-Type must be application/json.",
      ),
    );
    return;
  }

  next();
};

The media-type decision remains local to routes that consume JSON.
An unsupported representation creates a 415 AppError.
The middleware does not know how the final JSON envelope or request metadata should look.
The final error handler formats this error in exactly the same way as route-generated application errors.

This keeps representation enforcement and response formatting as separate responsibilities.

The final handler uses request context established near the start of the application.

TypeScript

function buildMeta(response: Response) {
  return {
    requestId: response.locals.requestId,
    durationMs:
      Date.now() -
      Number(
        response.locals.startedAt ?? Date.now(),
      ),
  };
}

function buildMeta(response: Response) {
  return {
    requestId: response.locals.requestId,
    durationMs:
      Date.now() -
      Number(
        response.locals.startedAt ?? Date.now(),
      ),
  };
}

requestId is the preserved or generated value created by requestContext.
durationMs measures elapsed time from the stored start timestamp until error formatting.
The fallback to Date.now() prevents an invalid calculation if context is unexpectedly missing.
Every error branch calls the same helper, so metadata remains consistent across validation, application, parser, database, and internal failures.

A typical error response now includes:

JSON

{
  "error": {
    "code": "TICKET_NOT_FOUND",
    "message": "Ticket not found."
  },
  "meta": {
    "requestId": "course3-checkpoint",
    "durationMs": 4
  }
}

{
  "error": {
    "code": "TICKET_NOT_FOUND",
    "message": "Ticket not found."
  },
  "meta": {
    "requestId": "course3-checkpoint",
    "durationMs": 4
  }
}

Successful ticket and comment responses remain resource-shaped. This course centralizes errors without wrapping successful data in a new envelope.

The first branch in src/middleware/error-handler.ts checks whether a response has already started.

TypeScript

if (response.headersSent) {
  next(error);
  return;
}

if (response.headersSent) {
  next(error);
  return;
}

Once response headers or body bytes have been sent, the application should not attempt to start a second JSON response.
Calling next(error) delegates the failure to Express’s remaining error handling instead.
Returning immediately prevents the custom middleware from continuing into one of its mapping branches.

This guard must come before every attempt to call response.status(...).json(...).

Application errors are handled before broader error categories.

TypeScript

if (error instanceof AppError) {
  response.status(error.statusCode).json({
    error: {
      code: error.code,
      message: error.message,
      ...(error.details === undefined
        ? {}
        : { details: error.details }),
    },
    meta: buildMeta(response),
  });
  return;
}

if (error instanceof AppError) {
  response.status(error.statusCode).json({
    error: {
      code: error.code,
      message: error.message,
      ...(error.details === undefined
        ? {}
        : { details: error.details }),
    },
    meta: buildMeta(response),
  });
  return;
}

The HTTP status, stable code, and message come directly from the error instance.
details is included only when it exists. Errors without extra context do not receive a meaningless details: undefined property.
Request metadata is attached by the centralized handler rather than by individual routes.
This one branch formats TICKET_NOT_FOUND, INVALID_AUTHOR, INVALID_REQUESTER, METHOD_NOT_ALLOWED, and UNSUPPORTED_MEDIA_TYPE.

Zod errors retain their dedicated safe mapping.

TypeScript

if (error instanceof ZodError) {
  response.status(400).json({
    error: {
      code: "VALIDATION_ERROR",
      message: "Request validation failed.",
      details: error.issues.map((issue) => ({
        path: issue.path.join("."),
        message: issue.message,
      })),
    },
    meta: buildMeta(response),
  });
  return;
}

if (error instanceof ZodError) {
  response.status(400).json({
    error: {
      code: "VALIDATION_ERROR",
      message: "Request validation failed.",
      details: error.issues.map((issue) => ({
        path: issue.path.join("."),
        message: issue.message,
      })),
    },
    meta: buildMeta(response),
  });
  return;
}

Validation failures always use HTTP 400.
Only safe issue paths and messages are returned. Internal schema objects or stack traces are not exposed.
Paths become readable dotted strings through join(".").
Request metadata is included just as it is for AppError.

A request with an unsupported priority can therefore return:

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      {
        "path": "priority",
        "message": "Invalid option: expected one of \"low\"|\"medium\"|\"high\""
      }
    ]
  },
  "meta": {
    "requestId": "course3-checkpoint",
    "durationMs": 2
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": [
      {
        "path": "priority",
        "message": "Invalid option: expected one of \"low\"|\"medium\"|\"high\""
      }
    ]
  },
  "meta": {
    "requestId": "course3-checkpoint",
    "durationMs": 2
  }
}

Malformed JSON fails inside express.json() before Zod receives a body. The error handler uses a type guard to recognize parser failures.

TypeScript

function isJsonSyntaxError(
  error: unknown,
): error is SyntaxError & {
  status?: number;
  type?: string;
} {
  return error instanceof SyntaxError &&
    (
      ("status" in error && error.status === 400) ||
      (
        "type" in error &&
        error.type === "entity.parse.failed"
      )
    );
}

function isJsonSyntaxError(
  error: unknown,
): error is SyntaxError & {
  status?: number;
  type?: string;
} {
  return error instanceof SyntaxError &&
    (
      ("status" in error && error.status === 400) ||
      (
        "type" in error &&
        error.type === "entity.parse.failed"
      )
    );
}

The error must be a SyntaxError, which matches JSON parsing failures.
Express body parsing may mark the error through status === 400, type === "entity.parse.failed", or both.
The helper avoids treating every random object as a malformed JSON error.

The matching branch returns a safe client response:

TypeScript

if (isJsonSyntaxError(error)) {
  response.status(400).json({
    error: {
      code: "INVALID_JSON",
      message:
        "Request body contains invalid JSON.",
    },
    meta: buildMeta(response),
  });
  return;
}

if (isJsonSyntaxError(error)) {
  response.status(400).json({
    error: {
      code: "INVALID_JSON",
      message:
        "Request body contains invalid JSON.",
    },
    meta: buildMeta(response),
  });
  return;
}

Malformed JSON is different from schema-invalid JSON:

text

Malformed syntax
{ "title": "Broken", }
→ 400 INVALID_JSON

Valid JSON with invalid data
{ "title": "Hi" }
→ 400 VALIDATION_ERROR

Malformed syntax
{ "title": "Broken", }
→ 400 INVALID_JSON

Valid JSON with invalid data
{ "title": "Hi" }
→ 400 VALIDATION_ERROR

The parser handles the first problem, while Zod handles the second.

Database errors can expose a code property. The helper reads it without assuming every unknown error has the expected shape.

TypeScript

function postgresCode(
  error: unknown,
): string | undefined {
  if (
    !error ||
    typeof error !== "object" ||
    !("code" in error)
  ) {
    return undefined;
  }

  const code =
    (error as { code?: unknown }).code;

  return typeof code === "string"
    ? code
    : undefined;
}

function postgresCode(
  error: unknown,
): string | undefined {
  if (
    !error ||
    typeof error !== "object" ||
    !("code" in error)
  ) {
    return undefined;
  }

  const code =
    (error as { code?: unknown }).code;

  return typeof code === "string"
    ? code
    : undefined;
}

The function checks that the value is a non-null object before reading code.
It returns a string only when the property actually contains one.
Unknown errors without a database code continue toward the generic fallback.

PostgreSQL code 23503 represents a foreign-key violation.

TypeScript

const code = postgresCode(error);

if (code === "23503") {
  response.status(400).json({
    error: {
      code: "REFERENCE_NOT_FOUND",
      message:
        "A referenced database record does not exist.",
    },
    meta: buildMeta(response),
  });
  return;
}

const code = postgresCode(error);

if (code === "23503") {
  response.status(400).json({
    error: {
      code: "REFERENCE_NOT_FOUND",
      message:
        "A referenced database record does not exist.",
    },
    meta: buildMeta(response),
  });
  return;
}

The client receives HTTP 400 because the requested mutation contains a reference PostgreSQL cannot satisfy.
The response does not expose table names, constraint names, SQL text, or database credentials.
The stable application code is REFERENCE_NOT_FOUND.

Route-level existence checks still provide more specific errors such as INVALID_AUTHOR. This database mapping remains a defensive fallback for foreign-key failures that reach PostgreSQL.

PostgreSQL code 23505 represents a uniqueness violation.

TypeScript

if (code === "23505") {
  response.status(409).json({
    error: {
      code: "CONFLICT",
      message:
        "The request conflicts with an existing database record.",
    },
    meta: buildMeta(response),
  });
  return;
}

if (code === "23505") {
  response.status(409).json({
    error: {
      code: "CONFLICT",
      message:
        "The request conflicts with an existing database record.",
    },
    meta: buildMeta(response),
  });
  return;
}

HTTP 409 Conflict communicates that the request cannot be completed because it conflicts with existing state.
The client receives a safe general explanation rather than the database’s raw constraint message.
Request context metadata remains available for investigation.

Every unrecognized error reaches the final fallback.

TypeScript

console.error(
  "Unhandled request error",
  error,
);

response.status(500).json({
  error: {
    code: "INTERNAL_SERVER_ERROR",
    message: "An unexpected error occurred.",
  },
  meta: buildMeta(response),
});

console.error(
  "Unhandled request error",
  error,
);

response.status(500).json({
  error: {
    code: "INTERNAL_SERVER_ERROR",
    message: "An unexpected error occurred.",
  },
  meta: buildMeta(response),
});

The complete error is logged server-side, where developers can diagnose it.
The API returns HTTP 500 with a stable INTERNAL_SERVER_ERROR code.
Stack traces, SQL details, filesystem paths, and credentials are not exposed to the client.
This branch must remain last so it does not swallow known application, validation, parser, or database failures.

The complete branch order is deliberate:

text

1. Response headers already sent
2. AppError
3. ZodError
4. Malformed JSON
5. PostgreSQL 23503
6. PostgreSQL 23505
7. Unexpected error

1. Response headers already sent
2. AppError
3. ZodError
4. Malformed JSON
5. PostgreSQL 23503
6. PostgreSQL 23505
7. Unexpected error

A generic fallback placed too early would convert useful failures such as TICKET_NOT_FOUND or VALIDATION_ERROR into undifferentiated 500 responses.

Specific known categories should always be checked before broader unknown failures.

src/middleware/not-found.ts handles requests that matched no application route.

TypeScript

export const notFound: RequestHandler = (
  request,
  response,
) => {
  response.status(404).json({
    error: {
      code: "NOT_FOUND",
      message:
        `Route ${request.method} ${request.originalUrl} was not found.`,
    },
    meta: {
      requestId: response.locals.requestId,
      durationMs:
        Date.now() -
        Number(
          response.locals.startedAt ??
            Date.now(),
        ),
    },
  });
};

This middleware runs only after all registered routes have declined the request.
The error code is the generic NOT_FOUND, not TICKET_NOT_FOUND.
The message includes both the attempted method and original URL.
Request context metadata is attached because requestContext ran at the beginning of the pipeline.

Compare these requests:

text

GET /api/tickets/tkt_missing

The path matches a ticket-detail route, but the resource is absent:

text

404 TICKET_NOT_FOUND

GET /api/unknown

No route matches the path:

404 NOT_FOUND

Both use HTTP 404, but their application meanings are different.

The router in src/routes/error-demo-routes.ts provides controlled examples without changing production ticket data.

An application error is thrown directly:

TypeScript

errorDemoRoutes.get("/app", () => {
  throw new AppError(
    418,
    "DEMO_APP_ERROR",
    "AppError reached the central handler.",
  );
});

errorDemoRoutes.get("/app", () => {
  throw new AppError(
    418,
    "DEMO_APP_ERROR",
    "AppError reached the central handler.",
  );
});

The final handler preserves the supplied status and code.
The route demonstrates that synchronous throws also enter Express error flow.

The async route demonstrates Express 5 promise forwarding:

TypeScript

errorDemoRoutes.get("/async", async () => {
  await Promise.resolve();

  throw new Error(
    "Rejected async route reached the central handler.",
  );
});

errorDemoRoutes.get("/async", async () => {
  await Promise.resolve();

  throw new Error(
    "Rejected async route reached the central handler.",
  );
});

The rejected async handler reaches the generic 500 branch without a wrapper.
No manual try/catch or next(error) call is required.

The Zod route triggers schema validation failure:

TypeScript

errorDemoRoutes.get("/zod", () => {
  z.object({
    value: z.string().min(3),
  }).parse({
    value: "x",
  });
});

errorDemoRoutes.get("/zod", () => {
  z.object({
    value: z.string().min(3),
  }).parse({
    value: "x",
  });
});

The simulated PostgreSQL routes expose safe error objects:

TypeScript

errorDemoRoutes.get(
  "/foreign-key",
  async () => {
    throw { code: "23503" };
  },
);

errorDemoRoutes.get(
  "/unique",
  async () => {
    throw { code: "23505" };
  },
);

errorDemoRoutes.get(
  "/foreign-key",
  async () => {
    throw { code: "23503" };
  },
);

errorDemoRoutes.get(
  "/unique",
  async () => {
    throw { code: "23505" };
  },
);

These routes let you verify every branch independently from actual database constraints.

Keep the base URL set to:

text

http://localhost:4000

http://localhost:4000

Send an unsupported collection method:

text

PUT /api/tickets

PUT /api/tickets

The response should use HTTP 405:

JSON

{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "PUT is not allowed for this route.",
    "details": {
      "allowedMethods": [
        "GET",
        "POST"
      ]
    }
  },
  "meta": {
    "requestId": "course3-checkpoint",
    "durationMs": 1
  }
}

{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "PUT is not allowed for this route.",
    "details": {
      "allowedMethods": [
        "GET",
        "POST"
      ]
    }
  },
  "meta": {
    "requestId": "course3-checkpoint",
    "durationMs": 1
  }
}

Inspect the response headers and confirm:

text

Allow: GET, POST

Allow: GET, POST

Test the detail resource:

text

POST /api/tickets/tkt_1001

POST /api/tickets/tkt_1001

Its Allow header should be:

text

GET, PATCH, DELETE

GET, PATCH, DELETE

Test nested comments:

text

DELETE /api/tickets/tkt_1001/comments

DELETE /api/tickets/tkt_1001/comments

Its Allow header should be:

text

GET, POST

GET, POST

Send ticket creation as text/plain:

text

POST /api/tickets
Content-Type: text/plain

POST /api/tickets
Content-Type: text/plain

This should produce:

text

415 UNSUPPORTED_MEDIA_TYPE

415 UNSUPPORTED_MEDIA_TYPE

Next, select JSON mode but send malformed syntax, such as:

JSON

{
  "title": "Broken JSON",
}

{
  "title": "Broken JSON",
}

The trailing comma makes the body invalid JSON, so the parser should produce:

text

400 INVALID_JSON

400 INVALID_JSON

Then send valid JSON with an invalid priority:

JSON

{
  "title": "Invalid enum example",
  "priority": "urgent",
  "requesterId": "usr_customer_1"
}

{
  "title": "Invalid enum example",
  "priority": "urgent",
  "requesterId": "usr_customer_1"
}

This should reach Zod and return:

text

400 VALIDATION_ERROR

400 VALIDATION_ERROR

Finally, send a validly shaped body with a nonexistent requester:

JSON

{
  "title": "Missing requester example",
  "requesterId": "usr_missing"
}

{
  "title": "Missing requester example",
  "requesterId": "usr_missing"
}

Zod accepts the shape, but the route’s database lookup should throw:

text

400 INVALID_REQUESTER

400 INVALID_REQUESTER

Add this header in the API Simulator:

text

X-Request-Id: error-map-001

X-Request-Id: error-map-001

Then request:

text

GET /api/error-demo/app
GET /api/error-demo/zod
GET /api/error-demo/foreign-key
GET /api/error-demo/unique
GET /api/error-demo/async

GET /api/error-demo/app
GET /api/error-demo/zod
GET /api/error-demo/foreign-key
GET /api/error-demo/unique
GET /api/error-demo/async

The expected mappings are:

text

/app         → supplied AppError status and DEMO_APP_ERROR
/zod        → 400 VALIDATION_ERROR
/foreign-key → 400 REFERENCE_NOT_FOUND
/unique      → 409 CONFLICT
/async       → 500 INTERNAL_SERVER_ERROR

/app         → supplied AppError status and DEMO_APP_ERROR
/zod        → 400 VALIDATION_ERROR
/foreign-key → 400 REFERENCE_NOT_FOUND
/unique      → 409 CONFLICT
/async       → 500 INTERNAL_SERVER_ERROR

Every response should contain:

JSON

{
  "meta": {
    "requestId": "error-map-001",
    "durationMs": 1
  }
}

{
  "meta": {
    "requestId": "error-map-001",
    "durationMs": 1
  }
}

The exact duration can vary, but it should be numeric.

Use one request ID for a full regression flow:

text

X-Request-Id: course3-checkpoint

X-Request-Id: course3-checkpoint

Create a ticket with valid JSON, copy its returned ID, and confirm the successful response still includes:

201 Created
The resource-shaped ticket body
A Location header
The echoed X-Request-Id response header

Patch the new ticket, add a nested comment, list the comment collection, and delete the ticket. Successful responses should remain unchanged by the error refactor.

Then compare:

text

GET /api/tickets/tkt_missing
GET /api/unknown

GET /api/tickets/tkt_missing
GET /api/unknown

The first should return TICKET_NOT_FOUND because the ticket route matched. The second should return NOT_FOUND because no route matched.

You’ve completed the course with one predictable Express 5 failure pipeline. AppError gives routes and middleware a reusable way to describe expected failures through an HTTP status, stable code, readable message, and optional details.

methodNotAllowed() adds correct 405 behavior and Allow headers without formatting responses locally. Ticket and comment routes now throw AppError from async handlers, while requireJson delegates its media-type failure with next(error).

The final error middleware safely distinguishes application errors, Zod failures, malformed JSON, PostgreSQL foreign-key violations, uniqueness conflicts, and unknown errors. Every error includes request metadata, while successful ticket and comment responses remain in their existing resource shapes.

With validation, request context, narrow representation guards, custom application errors, method fallbacks, database mappings, and safe 404 handling now working together, the API has a strong foundation for authentication, authorization, workflows, versioning, readiness, and production-focused testing.