Custom Error Classes: Beyond Generic Errors

Why it exists

JavaScript provides a generic Error object, but real applications have many distinct failure modes. A "user not found" error is fundamentally different from a "database connection failed" error. Relying on string matching error messages is brittle and error-prone. Custom error classes solve this by creating explicit, typed categories for failures.

The mental model

Think of custom errors like HTTP status codes. Instead of just "error" (like a generic 500), you have specific signals like 404 Not Found, 400 Bad Request, or 503 Service Unavailable. This allows consuming code, like an Express error-handling middleware, to know exactly what kind of response to send without inspecting the error message string.

How it works

You create a new class that extends the built-in Error class. The constructor for your custom class must call super() to properly initialize the parent Error object, passing the error message to it. This ensures your custom error inherits standard properties like message and a proper stack trace. You can then set a custom name property and add other properties, like a statusCode, to carry more context. For example: class NotFoundError extends Error { constructor(message) { super(message); this.name = 'NotFoundError'; this.statusCode = 404; } }.

When to use it

Use custom errors to differentiate between operational errors (expected failures, like invalid user input) and programmer errors (bugs). They are essential in API development for mapping specific failures to appropriate HTTP status codes. For instance, a ValidationError can map to a 400 response, while an AuthenticationError maps to a 401.

When not to use it

For simple scripts or small projects where there are only one or two expected failure types, a generic new Error('message') might be sufficient. Over-engineering with dozens of custom error classes for a small utility can add unnecessary complexity. The goal is clarity, not classification for its own sake.

One canonical example

In an Express.js API, a central error-handling middleware can inspect the type of error it receives. If a service throws new UserNotFoundError('User 123 not found'), the middleware can check if (err instanceof UserNotFoundError) and reliably send a 404 status code. If it catches a generic Error, it can default to a 500 Internal Server Error. This avoids fragile logic like if (err.message.includes('not found')).