🛡️ Error Handling Strategies

How Express Handles Errors

Express has a built-in mechanism for errors. When you call next(err) with an argument — or, in Express 5, when an async handler rejects — Express skips all remaining normal middleware and jumps straight to your error-handling middleware (the one with four parameters). Your job is to make that landing spot smart: log the problem, choose the right status code, and return a clean response.

🎪 The safety-net analogy. Error handling is like the safety nets at a circus. The performers (your handlers) attempt complex acts. Local nets (try/catch blocks) catch falls in specific spots. One big main net (the centralized error handler) spans the whole show to catch anything the local nets miss. And the emergency team (logging and monitoring) assesses every fall so the same accident doesn't happen twice.

Types of Errors

Not all errors are equal. Classifying them tells you whether to handle-and-respond or to crash-and-fix:

• Operational errors — expected runtime conditions you should handle gracefully: invalid input, auth failure, resource not found, a database timeout, rate-limit exceeded. These are normal; return a helpful response.
• Programming errors — bugs in your code: type errors, reading undefined, wrong logic. These should be fixed, not papered over. In production they surface as generic 500s while you get an alert.
• System errors — the environment failing: out of memory, disk full, network reset. Often unrecoverable at the request level; handle at the process level.

Choosing the right status code

Error-Handling Middleware

The foundation is a single middleware with four parameters, registered after all your routes. Here's a solid, security-aware version:

// Registered LAST, after all routes and other middleware
app.use((err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  let message = err.message || 'Something went wrong';

  // Log everything server-side
  console.error(`[ERROR] ${req.method} ${req.path} → ${statusCode}`, err.stack);

  // Never leak internal 500 details to clients in production
  if (statusCode === 500 && process.env.NODE_ENV === 'production') {
    message = 'An unexpected error occurred';
  }

  const body = { success: false, error: { message } };
  if (err.details) body.error.details = err.details;
  if (err.code) body.error.code = err.code;

  res.status(statusCode).json(body);
});

You also want a 404 handler for routes that don't match anything. Place it after your routes but before the error handler — it manufactures an error and forwards it:

// 404 — no route matched. Runs after all routes.
app.use((req, res, next) => {
  const err = new Error(`Not Found - ${req.originalUrl}`);
  err.statusCode = 404;
  next(err); // hand off to the error handler above
});

Custom Error Classes

Throwing a bare new Error('User not found') loses information — the handler can't tell it should be a 404. Custom error classes attach the status code and details right to the error, so any handler downstream knows exactly what to do.

// errors/ApiError.js — the base class
class ApiError extends Error {
  constructor(message, statusCode, details = null) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.details = details;
    this.isOperational = true; // distinguishes expected errors from bugs
    Error.captureStackTrace(this, this.constructor);
  }
}

module.exports = ApiError;

Then a small family of specific errors, each setting a sensible default status:

const ApiError = require('./ApiError');

class BadRequestError extends ApiError {
  constructor(message = 'Bad Request', details = null) { super(message, 400, details); }
}
class NotFoundError extends ApiError {
  constructor(resource = 'Resource') { super(`${resource} not found`, 404); }
}
class UnauthorizedError extends ApiError {
  constructor(message = 'Authentication required') { super(message, 401); }
}
class ForbiddenError extends ApiError {
  constructor(message = 'Access denied') { super(message, 403); }
}
class ValidationError extends ApiError {
  constructor(details) { super('Validation failed', 422, details); }
}

module.exports = { ApiError, BadRequestError, NotFoundError, UnauthorizedError, ForbiddenError, ValidationError };

Now handlers read like plain English, and the error carries its own status code:

const { NotFoundError, ForbiddenError } = require('./errors');

app.get('/api/users/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) throw new NotFoundError('User');           // → 404
    if (req.user.role !== 'admin' && req.user.id !== user.id) {
      throw new ForbiddenError('You can only view your own profile'); // → 403
    }
    res.json(user);
  } catch (err) {
    next(err); // the central handler reads err.statusCode
  }
});

// The central handler recognizes any ApiError
const { ApiError } = require('./errors');

app.use((err, req, res, next) => {
  if (err instanceof ApiError) {
    return res.status(err.statusCode).json({
      success: false,
      error: { message: err.message, ...(err.details && { details: err.details }) },
    });
  }
  // Unknown error = treat as 500
  console.error(err);
  res.status(500).json({
    success: false,
    error: { message: process.env.NODE_ENV === 'production' ? 'An unexpected error occurred' : err.message },
  });
});

Asynchronous Error Handling

Most real errors happen in async code. If a promise rejects and nobody catches it, the request stalls (Express 4) or crashes the process (unhandled rejection). Three patterns keep you safe.

1. try/catch around await

app.get('/api/users/:id', async (req, res, next) => {
  try {
    const user = await User.findById(req.params.id);
    if (!user) throw new NotFoundError('User');
    res.json(user);
  } catch (err) {
    next(err);
  }
});

2. An asyncHandler wrapper

const asyncHandler = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get('/api/users/:id', asyncHandler(async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) throw new NotFoundError('User');
  res.json(user);
}));

3. Global last-resort handlers

Even careful code can miss a rejection. Set up process-level guards so a stray error doesn't silently take down your server:

process.on('unhandledRejection', (reason) => {
  console.error('Unhandled Rejection:', reason);
  // Log to monitoring; in serious cases, shut down gracefully.
});

process.on('uncaughtException', (err) => {
  console.error('Uncaught Exception:', err);
  // An uncaught exception leaves the process in an unknown state —
  // log, then exit and let your process manager (PM2/systemd) restart it.
  server.close(() => process.exit(1));
  setTimeout(() => process.exit(1), 10_000).unref();
});

Centralized Error Handling

As an app grows, you want one place that knows how to turn any error — from Mongoose, Joi, JWT, or your own classes — into a consistent response. The trick is a normalizer that maps known error shapes onto your ApiError format:

// middleware/errorHandler.js
const { ApiError } = require('../errors');
const logger = require('../utils/logger');

// Map third-party error types to a standard ApiError
const normalize = (err) => {
  if (err instanceof ApiError) return err;

  // Mongoose duplicate key
  if (err.code === 11000) {
    const field = Object.keys(err.keyValue || {})[0];
    return new ApiError('A record with that value already exists', 409, { field });
  }
  // Mongoose validation
  if (err.name === 'ValidationError') {
    const details = Object.values(err.errors).map((e) => ({ field: e.path, message: e.message }));
    return new ApiError('Validation failed', 422, details);
  }
  // JWT
  if (err.name === 'JsonWebTokenError') return new ApiError('Invalid token', 401);
  if (err.name === 'TokenExpiredError') return new ApiError('Token has expired', 401);

  // Unknown → generic 500 (a probable bug)
  return new ApiError('An unexpected error occurred', 500);
};

const errorHandler = (err, req, res, next) => {
  const e = normalize(err);

  // Log with severity based on status
  const context = { path: req.path, method: req.method, requestId: req.id };
  if (e.statusCode >= 500) {
    logger.error({ message: e.message, stack: err.stack, ...context });
  } else {
    logger.warn({ message: e.message, ...context });
  }

  const body = { success: false, error: { message: e.message } };
  if (e.details) body.error.details = e.details;
  if (process.env.NODE_ENV === 'development') body.error.stack = err.stack;

  res.status(e.statusCode).json(body);
};

module.exports = errorHandler;

With this in place, your route handlers never format errors — they just throw or next(err), and one well-tested function handles the rest. This is exactly how large teams keep error responses uniform across hundreds of endpoints.

Logging & Monitoring

An error you don't record is an error you can't fix. In production you need structured logs (machine-parseable JSON) and, ideally, an error-tracking service that groups and alerts.

Structured logging with Winston

// utils/logger.js
const winston = require('winston');

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json(),
  ),
  defaultMeta: { service: 'api' },
  transports: [
    new winston.transports.Console(),
    ...(process.env.NODE_ENV === 'production'
      ? [new winston.transports.File({ filename: 'logs/error.log', level: 'error' })]
      : []),
  ],
});

module.exports = logger;

Error tracking with Sentry

// npm install @sentry/node
const Sentry = require('@sentry/node');

Sentry.init({ dsn: process.env.SENTRY_DSN, environment: process.env.NODE_ENV });

// In modern @sentry/node, set up the Express error handler after your routes:
Sentry.setupExpressErrorHandler(app);

// Then your own error handler runs last
app.use(errorHandler);

User-Friendly Responses

A good error response helps the caller fix the problem without exposing anything sensitive. Aim for a consistent envelope with a clear message, an optional machine-readable code, field-level details, and a request ID for support:

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "email", "message": "Email format is invalid" },
      { "field": "password", "message": "Password must be at least 8 characters" }
    ],
    "documentation": "https://api.example.com/docs/errors#validation"
  },
  "requestId": "7f77cc43-2019-4b55-9c7f-3b97238e0810"
}

Consistency is the theme running through this whole lesson: the same envelope on every endpoint, in every error path, so clients can write one error-handling routine that works everywhere. That predictability is exactly why Stripe, GitHub, and Twilio are praised for their developer experience.

Hands-on Exercise

const express = require('express');
const app = express();
app.use(express.json());

// --- Error classes ---
class ApiError extends Error {
  constructor(message, statusCode, details = null) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.details = details;
    Error.captureStackTrace(this, this.constructor);
  }
}
class NotFoundError extends ApiError {
  constructor(resource = 'Resource') { super(`${resource} not found`, 404); }
}
class BadRequestError extends ApiError {
  constructor(message = 'Bad Request', details = null) { super(message, 400, details); }
}

// --- Route ---
app.get('/api/items/:id', (req, res) => {
  if (req.params.id !== '1') throw new NotFoundError('Item');
  res.json({ success: true, data: { id: 1, name: 'Widget' } });
});

// --- 404 catch-all (after routes) ---
app.use((req, res, next) => {
  next(new NotFoundError(`Route ${req.originalUrl}`));
});

// --- Centralized error handler (LAST, four params) ---
app.use((err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  const body = { success: false, error: { message: err.message } };
  if (err.details) body.error.details = err.details;
  if (statusCode >= 500) console.error(err.stack);
  res.status(statusCode).json(body);
});

app.listen(3000, () => console.log('http://localhost:3000'));

Best Practices

Summary & Quiz

📚 Further Reading

• Express — Error Handling
• Node.js Best Practices — Error Handling
• http-errors package
• Winston logging library
• Sentry for Express

🚀 What's Next?

You've built a robust JavaScript backend — APIs, middleware, and error handling. Now the frontend calls: React Component Architecture begins building the user interface that will consume everything you've made.