Chapter 7 — Request Validation & Error Handling

The why

Validation is the single most security-relevant thing you'll write. Error handling is the single most debuggability-relevant. Both are boring. Both must be perfect.

Never trust the client

A client can:

• Send any header.
• Send any body.
• Skip the frontend validation by editing it.
• Replay an old request.
• Send a request from a script, not a browser.

Your server must validate everything, every time. Validation belongs on the server. The frontend can validate too — but only for UX, not for safety.

Zod — the modern way

We'll use Zod because it gives you runtime validation and TypeScript types from one schema.

npm install zod

Define a schema for "create note":

import { z } from 'zod';
 
export const createNoteSchema = z.object({
  title: z.string().min(1).max(200),
  body: z.

That schema says:

• title is a string, 1–200 chars, required.
• body is a string up to 10k chars, optional, defaults to "".
• tags is an array of strings (each non-empty), up to 20, optional.

The TypeScript type comes for free with z.infer<>. One source of truth.

Use it in a route:

import { createNoteSchema } from './schemas/notes';
 
router.post('/', (req, res, next) => {
  const result = createNoteSchema.safeParse(req.body

Now data is fully typed. Garbage in returns a structured 422.

Make validation a middleware

Don't duplicate the safeParse block in every route. Make it a middleware:

import { ZodSchema } from 'zod';
 
export function validate(schema: ZodSchema, where: 'body' | 'query' | 'params' = 'body') {
  return (req

Use:

router.post('/', validate(createNoteSchema), handler);
router.get('/',  validate(listNotesQuery, 'query'), handler);

Clean. Reusable. Easy to test.

Errors come in two flavors

This is the single most useful framing in error handling:

• Operational errors — the program is working correctly; the world is wrong. (User typed wrong password. DB is down. Third party API timed out.) → Handle and respond.
• Programmer errors — your code is broken. (Reading a property of undefined. Bad SQL. Forgot to await.) → Crash; let the orchestrator restart.

Mixing them up is why some services swallow their own crashes and keep serving broken responses.

class ApiError extends Error {
  constructor(public status: number, message: string, public code?: string) {
    super(message);
  }
}
 
// Throw it from a service:

The error middleware sees the status, returns it. Anything not an ApiError becomes a 500 and triggers an alert.

The one error middleware

import { ZodError } from 'zod';
 
export function errorHandler(err, req, res, _next) {
  // Zod (in case validation slipped through)
  if (err instanceof ZodError) {
    return res

Wire it in last:

app.use(errorHandler);

Now any thrown ApiError becomes a clean JSON response. Any unexpected error becomes a 500, gets logged, and surfaces a request ID the user can quote.

A good error response shape

Frontends love consistent shapes. Pick one and stick to it:

{
  "error": "Email is already in use",
  "code": "EMAIL_TAKEN",
  "requestId": "01HN4R...",
  "issues": [
    { "path": ["email"], "message": "

• error — human-readable.
• code — machine-readable (frontend i18n).
• requestId — so the user can quote it.
• issues — for multi-field validation.

Bad shapes you'll see in the wild:

"error: User already exists"

A bare string. Frontends can't internationalize.

{ "status": 200, "error": true, "msg": "User already exists" }

A 200 carrying a "failure." Tooling can't tell.

Async errors (revisited)

Express 4 doesn't catch async throws. Use the asyncHandler wrapper from chapter 5:

const wrap = fn => (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
 
router.post('

Now any throw new ApiError(...) inside notesService.create flows to the error middleware.

Validating query strings and route params

Query strings are always strings — you'll often need to coerce:

const listNotesQuery = z.object({
  limit: z.coerce.number().int().min(1).max(100).default(20),
  cursor: z.string()

z.coerce.number() parses "20" into 20. After validation, req.query.limit is a number.

For UUID route params:

const idParam = z.object({ id: z.string().uuid() });
router.get('/:id', validate(idParam, 'params'), handler);

Now invalid UUIDs never reach your handler. Free SQL-injection defense.

What about thrown errors in the database?

Database libraries (Prisma, pg) throw specific error types. Translate them to your ApiError:

try {
  return await prisma.user.create({ data });
} catch (err) {
  if (err.code === 'P2002') {
    throw new ApiError(409, '

Don't leak DB error messages directly. They sometimes contain schema info that helps attackers.

Common mistakes

Production · Performance · Security notes

Production. Wire unhandledRejection and uncaughtException to log + exit. Let the orchestrator restart you. A zombie Node process is worse than a restart.

process.on('unhandledRejection', err => {
  console.error('unhandledRejection', err);
  process.exit(1);
});

Performance. Zod validation is fast (microseconds for typical bodies). Don't micro-optimize before you measure.

Security. Hide internal codes in 500 responses. requestId lets users quote it; the actual exception lives only in your logs.

Exercises

1. Beginner. Add a Zod schema for PATCH /notes/:id. All fields optional.
2. Beginner. Validate req.query.limit as a number, default 20, max 100.
3. Intermediate. Throw a ApiError(409, ...) when inserting a duplicate email.
4. Intermediate. Add a requestId to every log line and error response.
5. Advanced. Write a middleware that auto-converts thrown Prisma errors into ApiErrors.

Interview questions

Beginner. What status code for a failed validation? 422 (Unprocessable Entity) is canonical; 400 is widely accepted.

Senior. How do you distinguish operational from programmer errors? Operational: known failure modes (DB down, validation failed, third party 500). Programmer: bugs (undefined property, missing await). Operational gets handled; programmer gets logged and the process restarted.

Summary

Validate every incoming request with Zod. Make validation a reusable middleware. Throw typed ApiErrors from your service layer. Catch all errors in one error middleware that returns a consistent JSON shape with a request ID. Distinguish operational errors (return 4xx) from programmer errors (log + crash + restart). With this in place your API responds cleanly to every possible input.

Quick recall

• Zod for validation. safeParse returns success/issues.
• Validation middleware keeps routes clean.
• ApiError carries the status code through to the response.
• One error handler, last.
• Operational vs programmer errors: handle vs crash.

Quiz

1. What status code should a validation error return?
2. Why must validation also run on the server, not just the frontend?
3. What's the difference between operational and programmer errors?
4. Why include a requestId in every error response?
5. What does z.coerce.number() do?