Handling Custom Errors in Node.js with a Custom ApiError Class

When building robust applications in Node.js, especially with frameworks like Express, error handling becomes essential. A common requirement in APIs is to return appropriate HTTP status codes along with descriptive error messages. This is where custom error classes come into play. In this blog, we'll explore how to create and use a custom ApiError class that can streamline error handling and improve the clarity of API responses.

The ApiError Class

Let's take a look at a simple yet powerful custom error class: ApiError.

class ApiError extends Error {
  statusCode: number;
  stack?: string | undefined;

  constructor(statusCode: number, message: string) {
    super(message);
    this.statusCode = statusCode;
    Error.captureStackTrace(this, this.constructor);
  }
}

export default ApiError;

Understanding the Code

Extending the Error Class:
The ApiError class extends JavaScript's built-in Error class, so it inherits all properties and methods of the standard error object, including the message and stack properties.

Adding the statusCode Property:
One of the key features of the ApiError class is the addition of the statusCode property. This represents the HTTP status code that should be returned when the error occurs. It's common to use status codes like 400 for "Bad Request", 401 for "Unauthorized", 404 for "Not Found", and 500 for "Internal Server Error".

The Constructor:
The constructor takes two arguments:

• statusCode: the HTTP status code that is associated with the error.
• message: a string message describing the error. Inside the constructor, we call super(message) to initialize the base Error class with the message. Then, we manually assign the statusCode to the instance. Finally, we use Error.captureStackTrace(this, this.constructor) to capture a proper stack trace for debugging.

Stack Trace Handling:
Error.captureStackTrace() is a V8-specific function that allows us to capture a stack trace that is more reliable than the standard stack property of an error. This is particularly helpful in Node.js environments when you need to understand the error's origins.

Using ApiError in Your Application

With the ApiError class in place, handling errors in your application becomes much more straightforward. Here's an example of how you can use it in an Express route.

import express, { Request, Response, NextFunction } from 'express';
import ApiError from './ApiError';

const app = express();

app.get('/api/resource', (req: Request, res: Response, next: NextFunction) => {
  try {
    // Simulate an error (e.g., resource not found)
    throw new ApiError(404, 'Resource not found');
  } catch (error) {
    next(error);
  }
});

app.use((err: ApiError, req: Request, res: Response, next: NextFunction) => {
  if (err instanceof ApiError) {
    res.status(err.statusCode).json({
      message: err.message,
      stack: err.stack,
    });
  } else {
    res.status(500).json({ message: 'Internal Server Error' });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Explanation

Throwing an ApiError:
In the /api/resource route, an error is intentionally thrown using the ApiError class. The error specifies a 404 status code, indicating that the requested resource was not found, along with a descriptive message.

Error Handling Middleware:
In the error handling middleware, we check if the error is an instance of ApiError. If it is, we respond with the statusCode and message from the error. Additionally, we include the stack trace for debugging purposes (although you may want to exclude this in production). If the error isn't an instance of ApiError, we default to sending a 500 Internal Server Error response.

Benefits of Using ApiError
Improved Clarity:
The ApiError class provides a structured way to handle errors, making it clear what the error is about and what HTTP status code should be returned.

Consistency:
By using a custom error class throughout your application, all errors are handled in a similar manner, leading to more predictable behavior and better maintainability.

Simplified Debugging:
The stack trace captured by Error.captureStackTrace() makes it easier to trace the source of errors, speeding up the debugging process.

Customizability:
You can further extend the ApiError class to include more custom properties (like errors for validation errors or code for custom error codes) depending on your application's requirements.

Conclusion

In Node.js applications, especially those using frameworks like Express, error handling is a critical part of the development process. By using a custom error class like ApiError, you can simplify error management, improve consistency, and make your code more maintainable.

With the ApiError class, you now have a powerful tool to handle errors in your API with status codes, messages, and stack traces. This approach not only improves your API's reliability but also helps developers consuming your API to quickly understand and handle errors in a standardized way.

Best Regards,
N I Rimon