Exception Handling (Framework Level)

This topic assumes familiarity with backend/frameworks/06-middleware (the request-handling chain an exception filter hooks into) and connects to backend/api-design/09-error_response_design, which defines the shape an error response should have. This topic is about the framework mechanism that catches a thrown error anywhere in the request-handling chain and converts it into that shape — it does not re-cover the response-shape design itself.

1The Problem: an Uncaught Throw Anywhere Crashes the Response

A request handler is just a function call, several layers deep (middleware -> routing -> controller -> service -> repository). Without a framework-level mechanism, a thrown error inside a service ten calls deep has to be manually caught at every intermediate layer, or it propagates all the way up and either crashes the process or leaves the HTTP response hanging with no status code ever sent:

// Without a global handler: every route must remember to try/catch, by hand
app.get("/orders/:id", async (req, res) => {
  try {
    const order = await orderService.findById(req.params.id);
    res.json(order);
  } catch (err) {
    res.status(500).json({ error: "something went wrong" }); // easy to forget, copy-pasted everywhere
  }
});

Repeating this try/catch in every single handler is both tedious and, in practice, inconsistently applied — some handler somewhere inevitably forgets it.

2Global Exception Filters/Middleware

A framework-level exception handler sits at the edge of the request-handling chain and catches whatever an inner layer throws, exactly once, in one place:

// Express: error-handling middleware is recognized by its 4-argument signature
function globalErrorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
  if (err instanceof NotFoundError) return res.status(404).json({ error: err.message });
  if (err instanceof ValidationError) return res.status(400).json({ error: err.message });
  console.error(err); // anything unrecognized: log it, never leak internals to the client
  res.status(500).json({ error: "internal server error" });
}

app.use(routes);
app.use(globalErrorHandler); // registered LAST — Express routes any thrown/next(err) error here

// NestJS: an @Catch() exception filter serves the same role
@Catch()
class GlobalExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();
    if (exception instanceof NotFoundException) {
      return res.status(404).json({ error: exception.message });
    }
    res.status(500).json({ error: "internal server error" });
  }
}

Now every handler can simply throw a meaningful error and trust that something, in exactly one place, converts it into the right HTTP response — no handler needs its own try/catch for the common case.

3Custom Exception Classes for Domain Errors

Throwing a plain Error everywhere gives the global handler nothing to distinguish "this resource doesn't exist" from "this input was invalid" from "something genuinely broke." Custom exception classes carry that distinction as a type the handler can branch on:

class NotFoundError extends Error {
  constructor(resource: string, id: string | number) {
    super(`${resource} ${id} not found`);
  }
}

class ValidationError extends Error {
  constructor(message: string, public readonly field?: string) {
    super(message);
  }
}

class ForbiddenError extends Error {}

// Deep inside a service, far from any HTTP concern:
async function findOrder(id: number) {
  const order = await orderRepo.findById(id);
  if (!order) throw new NotFoundError("Order", id); // the SERVICE doesn't know or care about HTTP status codes
  return order;
}

Critically, the service layer throws domain-meaningful errors — NotFoundError, ValidationError — without importing anything HTTP-specific. The mapping from "which error class" to "which HTTP status code" is the global handler's job, and only its job; this keeps the service layer (backend/frameworks/10-services_and_repositories) ignorant of the transport it happens to be running behind, which matters if the same service is ever called from a non-HTTP context (a background job, a CLI script).

4Global vs. Route-Scoped Handling

Most exception handling should be global — one handler, one mapping table from error class to status code, applied uniformly. A route-scoped (or controller-scoped) filter is the exception, reserved for genuinely local behavior a small subset of endpoints need that shouldn't apply everywhere:

@Controller("webhooks")
@UseFilters(WebhookExceptionFilter) // only THIS controller's routes use this filter
class WebhookController { /* ... */ }

Reaching for a route-scoped filter as the default (one custom filter per controller) reproduces the exact duplication problem the global handler exists to solve — it should be the deliberate exception, not the norm.

5What the Handler Must Never Do: Leak Internals

The one universal rule for the "unrecognized error" fallback branch (section 2's console.error(err) case) is that the response sent to the client must never include the raw error message, stack trace, or any internal detail — only a generic message. The full error belongs in the server's logs (see devops-cloud/observability/01-logging), not in the HTTP response body, since a stack trace can reveal file paths, library versions, or query structure useful to an attacker.

⚠️ Common Pitfalls

1. Wrapping every single handler in its own try/catch "to be safe." Reintroduces the exact duplication a global handler exists to eliminate, and inconsistency creeps in the moment one handler is written without it.
2. Throwing plain Error instead of a typed exception class. The global handler has nothing to branch on beyond string-matching a message, which is fragile and easy to get wrong as messages change.
3. Letting the service layer import HTTP-specific exception types (e.g. a NotFoundException tied to a specific framework's HTTP module). Couples business logic to a transport it may not always run behind; a plain domain-level NotFoundError class, mapped to a status code only in the handler, avoids this.
4. Leaking the raw error or stack trace in the response body for unrecognized errors. Section 5 — always log the full detail server-side, always send a generic message to the client for anything not explicitly recognized.
5. Defaulting to route-scoped filters instead of one global handler. Fragments the error-handling logic across every controller instead of keeping one consistent mapping in one place.

📋 Quick Reference

Global exception handler -> ONE place that catches anything thrown, maps it to a response
Custom exception classes  -> NotFoundError, ValidationError, etc. — typed, HTTP-agnostic
Service layer             -> throws domain errors, never imports HTTP-specific exception types
Handler's job              -> map error class -> HTTP status code + safe response body
Unrecognized error         -> log full detail server-side, send ONLY a generic message to the client
Route-scoped filter        -> the deliberate exception, not the default

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: fw_exception_handling_theory.md · generated by tools/build_lessons.py