Custom Error Classes and Advanced Error Handling

Custom error classes are the foundation of a maintainable error handling strategy. When all errors in an application are generic Error objects with only a message string, it is impossible to distinguish “user sent invalid data” from “database is down” from “third-party API rate limited us” — they all look the same to error handlers. A class hierarchy of application-specific errors, with properties for HTTP status codes, error codes, operational vs programmer distinction, and structured context, enables error handlers to respond differently to each type without parsing error messages — a fragile, impossible-to-maintain approach.

Error Classification #

Complete Error Handling System #

// src/errors/app-errors.js — custom error class hierarchy

class AppError extends Error {
    constructor(message, options = {}) {
        super(message, { cause: options.cause });   // ES2022 cause chaining
        this.name           = this.constructor.name;
        this.statusCode     = options.statusCode ?? 500;
        this.code           = options.code ?? 'INTERNAL_ERROR';
        this.isOperational  = options.isOperational ?? false;
        this.context        = options.context ?? {};  // extra structured context

        // Capture stack trace excluding the constructor itself
        if (Error.captureStackTrace) {
            Error.captureStackTrace(this, this.constructor);
        }
    }

    toJSON() {
        return {
            name:       this.name,
            message:    this.message,
            code:       this.code,
            statusCode: this.statusCode,
            context:    this.context,
        };
    }
}

class ValidationError extends AppError {
    constructor(message, fields = {}) {
        super(message, { statusCode: 400, code: 'VALIDATION_ERROR', isOperational: true });
        this.fields = fields;  // { fieldName: 'error message' }
    }
}

class AuthenticationError extends AppError {
    constructor(message = 'Authentication required', code = 'AUTH_REQUIRED') {
        super(message, { statusCode: 401, code, isOperational: true });
    }
}

class AuthorizationError extends AppError {
    constructor(message = 'Insufficient permissions') {
        super(message, { statusCode: 403, code: 'FORBIDDEN', isOperational: true });
    }
}

class NotFoundError extends AppError {
    constructor(resource = 'Resource', id = null) {
        super(id ? `${resource} '${id}' not found` : `${resource} not found`,
            { statusCode: 404, code: 'NOT_FOUND', isOperational: true });
        this.resource = resource;
        this.id       = id;
    }
}

class ConflictError extends AppError {
    constructor(message, field = null) {
        super(message, { statusCode: 409, code: 'CONFLICT', isOperational: true });
        this.field = field;
    }
}

class RateLimitError extends AppError {
    constructor(retryAfterSeconds = 60) {
        super(`Rate limit exceeded. Retry after ${retryAfterSeconds} seconds`,
            { statusCode: 429, code: 'RATE_LIMITED', isOperational: true });
        this.retryAfter = retryAfterSeconds;
    }
}

class ExternalServiceError extends AppError {
    constructor(service, message, { cause } = {}) {
        super(`${service} unavailable: ${message}`,
            { statusCode: 503, code: 'EXTERNAL_SERVICE_ERROR', isOperational: true, cause });
        this.service = service;
    }
}

module.exports = {
    AppError, ValidationError, AuthenticationError, AuthorizationError,
    NotFoundError, ConflictError, RateLimitError, ExternalServiceError,
};

// ── Express global error handler ──────────────────────────────────────────
// src/middleware/error.middleware.js
const { AppError } = require('../errors/app-errors');

module.exports = function errorHandler(err, req, res, next) {
    // Convert known framework errors to AppError subclasses
    if (err.name === 'ValidationError' && err.errors) {
        // Mongoose validation error
        const fields = Object.fromEntries(
            Object.entries(err.errors).map(([k, v]) => [k, v.message])
        );
        err = new ValidationError('Validation failed', fields);
    }
    if (err.name === 'CastError') {
        err = new NotFoundError('Resource', req.params.id);
    }
    if (err.code === 11000) {
        const field = Object.keys(err.keyPattern)[0];
        err = new ConflictError(`${field} already in use`, field);
    }

    // Programmer error — unexpected, log at error level
    if (!(err instanceof AppError) || !err.isOperational) {
        logger.error('Programmer error', {
            error:  err.message,
            stack:  err.stack,
            cause:  err.cause?.message,
            method: req.method,
            path:   req.path,
        });

        return res.status(500).json({
            message: process.env.NODE_ENV === 'production'
                ? 'Internal server error'
                : err.message,
        });
    }

    // Operational error — expected, log at warn level
    logger.warn('Operational error', {
        code:    err.code,
        status:  err.statusCode,
        message: err.message,
        context: err.context,
        path:    req.path,
    });

    const response = {
        message: err.message,
        code:    err.code,
    };
    if (err.fields)      response.fields      = err.fields;
    if (err.retryAfter)  response.retryAfter  = err.retryAfter;

    res.status(err.statusCode).json({ success: false, error: response });
};

How It Works #

Step 1 — Error.captureStackTrace Produces Clean Stack Traces #

Error.captureStackTrace(this, this.constructor) populates this.stack with the V8 stack trace, excluding the constructor call itself. Without this, the stack trace starts with the AppError constructor call rather than the actual throw site — making it harder to locate the problem. The second argument tells V8 where to start the trace, hiding the internal error class infrastructure from developers reading stack traces.

Step 2 — isOperational Distinguishes Expected from Unexpected #

Operational errors (isOperational: true) are conditions the application anticipated and can handle gracefully: user not found, validation failed, rate limited. They should not trigger alerts. Programmer errors (isOperational: false or not an AppError at all) indicate a bug and should trigger an on-call alert. The error handler checks this flag to decide between a warn log (operational) and an error log with potential process restart (programmer error).

Step 3 — Error Conversion Normalises Framework Errors #

Mongoose, Express, and other libraries throw their own error types. The global error handler converts known framework error types to AppError subclasses: Mongoose ValidationError → application ValidationError, Mongoose CastError → NotFoundError, MongoDB 11000 duplicate key → ConflictError. This normalisation means route handlers and services only need to throw AppError subclasses — framework errors are handled in one place.

Step 4 — Error Cause Chaining Preserves Root Cause #

ES2022’s cause option in new Error(message, { cause: originalError }) attaches the original error as a property. When a Mongoose error causes a service-level error, the chain preserves both: the service error describes the business operation that failed, and err.cause shows the technical MongoDB error that caused it. Logging both gives operational teams the full picture without exposing technical details in the API response.

Step 5 — Different Error Types Generate Different Responses #

Each AppError subclass carries its own statusCode and any type-specific fields (ValidationError.fields, RateLimitError.retryAfter). The global error handler reads these and constructs the appropriate response. This separation means the business logic (which throws the error) is decoupled from the HTTP presentation (which formats the response) — changing how rate limit errors are presented only requires updating the error handler, not every place that throws RateLimitError.

Quick Reference #