Error Handling Patterns: Building Resilient Node.js Applications

Proper error handling distinguishes production-ready applications from prototypes. This guide covers error handling patterns for Node.js and TypeScript applications.

Custom Error Classes#

Error Hierarchy#

// Base application error
export class AppError extends Error {
  public readonly isOperational: boolean;
  public readonly statusCode: number;
  public readonly code: string;

  constructor(
    message: string,
    statusCode: number = 500,
    code: string = 'INTERNAL_ERROR',
    isOperational: boolean = true
  ) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = statusCode;
    this.code = code;
    this.isOperational = isOperational;

    Error.captureStackTrace(this, this.constructor);
  }
}

// Specific error types
export class ValidationError extends AppError {
  public readonly details: Array<{ field: string; message: string }>;

  constructor(message: string, details: Array<{ field: string; message: string }> = []) {
    super(message, 400, 'VALIDATION_ERROR');
    this.details = details;
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id?: string) {
    const message = id
      ? `${resource} with ID ${id} not found`
      : `${resource} not found`;
    super(message, 404, 'NOT_FOUND');
  }
}

export class UnauthorizedError extends AppError {
  constructor(message: string = 'Authentication required') {
    super(message, 401, 'UNAUTHORIZED');
  }
}

export class ForbiddenError extends AppError {
  constructor(message: string = 'Access denied') {
    super(message, 403, 'FORBIDDEN');
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super(message, 409, 'CONFLICT');
  }
}

export class RateLimitError extends AppError {
  public readonly retryAfter: number;

  constructor(retryAfter: number) {
    super('Rate limit exceeded', 429, 'RATE_LIMIT_EXCEEDED');
    this.retryAfter = retryAfter;
  }
}

Result Type Pattern#

Type-Safe Error Handling#

type Result<T, E = Error> =
  | { success: true; data: T }
  | { success: false; error: E };

function ok<T>(data: T): Result<T, never> {
  return { success: true, data };
}

function err<E>(error: E): Result<never, E> {
  return { success: false, error };
}

// Usage in services
async function getUserById(id: string): Promise<Result<User, NotFoundError>> {
  const user = await db.users.findById(id);

  if (!user) {
    return err(new NotFoundError('User', id));
  }

  return ok(user);
}

// Usage in controllers
async function getUser(req: Request, res: Response) {
  const result = await getUserById(req.params.id);

  if (!result.success) {
    return res.status(result.error.statusCode).json({
      code: result.error.code,
      message: result.error.message,
    });
  }

  return res.json(result.data);
}

With neverthrow Library#

import { ok, err, Result, ResultAsync } from 'neverthrow';

class UserService {
  findById(id: string): ResultAsync<User, NotFoundError> {
    return ResultAsync.fromPromise(
      db.users.findById(id),
      () => new NotFoundError('User', id)
    ).andThen(user =>
      user ? ok(user) : err(new NotFoundError('User', id))
    );
  }

  create(data: CreateUserData): ResultAsync<User, ValidationError | ConflictError> {
    return this.validateUser(data)
      .asyncAndThen(validated =>
        this.checkEmailUnique(validated.email)
          .andThen(() => this.saveUser(validated))
      );
  }
}

// Chaining results
const result = await userService.findById('123')
  .andThen(user => orderService.findByUser(user.id))
  .map(orders => ({ orders, count: orders.length }));

result.match(
  data => res.json(data),
  error => res.status(error.statusCode).json({ error: error.message })
);

Express Error Handling#

Async Handler Wrapper#

type AsyncHandler = (
  req: Request,
  res: Response,
  next: NextFunction
) => Promise<any>;

function asyncHandler(fn: AsyncHandler): RequestHandler {
  return (req, res, next) => {
    Promise.resolve(fn(req, res, next)).catch(next);
  };
}

// Usage
app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await userService.findById(req.params.id);

  if (!user) {
    throw new NotFoundError('User', req.params.id);
  }

  res.json(user);
}));

Global Error Handler#

interface ErrorResponse {
  code: string;
  message: string;
  details?: unknown;
  stack?: string;
}

function errorHandler(
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction
): void {
  // Log error
  logger.error({
    error: {
      name: err.name,
      message: err.message,
      stack: err.stack,
    },
    request: {
      method: req.method,
      path: req.path,
      query: req.query,
      body: sanitize(req.body),
      headers: {
        'user-agent': req.headers['user-agent'],
        'x-request-id': req.headers['x-request-id'],
      },
    },
  });

  // Handle operational errors
  if (err instanceof AppError) {
    const response: ErrorResponse = {
      code: err.code,
      message: err.message,
    };

    if (err instanceof ValidationError) {
      response.details = err.details;
    }

    if (err instanceof RateLimitError) {
      res.set('Retry-After', err.retryAfter.toString());
    }

    res.status(err.statusCode).json(response);
    return;
  }

  // Handle Prisma errors
  if (err.name === 'PrismaClientKnownRequestError') {
    const prismaError = err as PrismaClientKnownRequestError;

    if (prismaError.code === 'P2002') {
      res.status(409).json({
        code: 'CONFLICT',
        message: 'A record with this value already exists',
      });
      return;
    }

    if (prismaError.code === 'P2025') {
      res.status(404).json({
        code: 'NOT_FOUND',
        message: 'Record not found',
      });
      return;
    }
  }

  // Handle validation errors (Zod, Joi, etc.)
  if (err.name === 'ZodError') {
    res.status(400).json({
      code: 'VALIDATION_ERROR',
      message: 'Invalid request data',
      details: (err as ZodError).errors,
    });
    return;
  }

  // Unknown errors
  const response: ErrorResponse = {
    code: 'INTERNAL_ERROR',
    message: process.env.NODE_ENV === 'production'
      ? 'An unexpected error occurred'
      : err.message,
  };

  if (process.env.NODE_ENV !== 'production') {
    response.stack = err.stack;
  }

  res.status(500).json(response);
}

// Apply middleware
app.use(errorHandler);

Retry Patterns#

Exponential Backoff#

interface RetryOptions {
  maxAttempts: number;
  baseDelayMs: number;
  maxDelayMs: number;
  retryOn?: (error: Error) => boolean;
}

async function withRetry<T>(
  fn: () => Promise<T>,
  options: RetryOptions
): Promise<T> {
  const { maxAttempts, baseDelayMs, maxDelayMs, retryOn } = options;

  let lastError: Error;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;

      // Check if we should retry
      if (retryOn && !retryOn(lastError)) {
        throw lastError;
      }

      if (attempt === maxAttempts) {
        throw lastError;
      }

      // Calculate delay with exponential backoff and jitter
      const delay = Math.min(
        baseDelayMs * Math.pow(2, attempt - 1) + Math.random() * 100,
        maxDelayMs
      );

      logger.warn({
        message: 'Retrying operation',
        attempt,
        maxAttempts,
        delay,
        error: lastError.message,
      });

      await sleep(delay);
    }
  }

  throw lastError!;
}

// Usage
const data = await withRetry(
  () => fetchFromExternalAPI(url),
  {
    maxAttempts: 3,
    baseDelayMs: 1000,
    maxDelayMs: 10000,
    retryOn: (error) => {
      // Retry on network errors and 5xx responses
      return error.name === 'FetchError' ||
             (error instanceof APIError && error.statusCode >= 500);
    },
  }
);

Circuit Breaker#

enum CircuitState {
  CLOSED = 'CLOSED',
  OPEN = 'OPEN',
  HALF_OPEN = 'HALF_OPEN',
}

class CircuitBreaker {
  private state: CircuitState = CircuitState.CLOSED;
  private failureCount: number = 0;
  private lastFailureTime: number = 0;
  private successCount: number = 0;

  constructor(
    private options: {
      failureThreshold: number;
      resetTimeout: number;
      halfOpenRequests: number;
    }
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === CircuitState.OPEN) {
      if (Date.now() - this.lastFailureTime >= this.options.resetTimeout) {
        this.state = CircuitState.HALF_OPEN;
        this.successCount = 0;
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess(): void {
    if (this.state === CircuitState.HALF_OPEN) {
      this.successCount++;
      if (this.successCount >= this.options.halfOpenRequests) {
        this.state = CircuitState.CLOSED;
        this.failureCount = 0;
      }
    } else {
      this.failureCount = 0;
    }
  }

  private onFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();

    if (this.failureCount >= this.options.failureThreshold) {
      this.state = CircuitState.OPEN;
    }
  }
}

Process-Level Error Handling#

// Handle uncaught exceptions
process.on('uncaughtException', (error: Error) => {
  logger.fatal({ error }, 'Uncaught exception');

  // Graceful shutdown
  gracefulShutdown(1);
});

// Handle unhandled promise rejections
process.on('unhandledRejection', (reason: unknown, promise: Promise<unknown>) => {
  logger.error({ reason, promise }, 'Unhandled rejection');

  // In production, you might want to crash
  // throw reason;
});

// Graceful shutdown
async function gracefulShutdown(exitCode: number = 0): Promise<void> {
  logger.info('Starting graceful shutdown...');

  // Stop accepting new connections
  server.close();

  // Close database connections
  await db.$disconnect();

  // Close Redis connections
  await redis.quit();

  logger.info('Shutdown complete');
  process.exit(exitCode);
}

process.on('SIGTERM', () => gracefulShutdown(0));
process.on('SIGINT', () => gracefulShutdown(0));

Best Practices#

Use typed errors: Create specific error classes for different scenarios
Don't swallow errors: Always handle or propagate errors
Log with context: Include request IDs, user IDs, and relevant data
Fail fast: Validate inputs early and throw immediately
Be consistent: Use the same error format throughout your API
Provide actionable messages: Help users understand what went wrong

Good error handling makes applications maintainable and debuggable. Use custom error classes for type safety, implement proper async handling, and ensure graceful degradation. Remember to handle both expected errors (validation, not found) and unexpected ones (bugs, infrastructure failures).