HTTP Error Classes

2.3.0 verified Thu Apr 23 auth: no javascript abandoned

The `httperrors` package provides a collection of JavaScript Error classes corresponding to standard HTTP 4xx and 5xx status codes. It allows developers to create instances of these errors either by their numeric status code (e.g., `httpErrors(404)`) or by their UpperCamelCase name (e.g., `new httpErrors.NotFound('Resource not found')`). Each error instance includes the HTTP status code and exposes its CamelCased name as a boolean property, which simplifies error type checking in conditional statements without relying on `instanceof`. Originally designed for use with web frameworks like Express, it facilitates consistent error handling by associating a `statusCode` property with error objects, enabling middleware to set appropriate HTTP response codes. The package is currently at version 2.3.0, with its last update over seven years ago, indicating that it is no longer actively maintained.

Common errors

error TypeError: httpErrors is not a function ↓

cause This error occurs when attempting to call `httpErrors` as a function after an incorrect ESM import, typically when `httpErrors` resolves to the module object itself instead of the factory function.

fix

Confirm you are using the CommonJS require syntax: const httpErrors = require('httperrors');. This package is not designed for ESM import statements.

error Error [ERR_REQUIRE_ESM]: require() of ES Module C:\path\to\node_modules\httperrors\index.js not supported ↓

cause This error arises when a Node.js project configured as an ES module (`"type": "module"` in `package.json`) attempts to `require()` a CommonJS module, which is the format of `httperrors`.

fix

In an ESM project, you cannot directly require() CommonJS modules. Consider using dynamic import('httperrors') or, preferably, switch to a modern HTTP error library that provides native ESM support. Alternatively, if your project can be CommonJS, remove "type": "module" from your package.json.

Warnings

breaking This package is abandoned, with its last release over 7 years ago. It is unlikely to receive updates for critical bug fixes, security vulnerabilities, or compatibility with newer Node.js versions or JavaScript features (like ESM). ↓

fix Consider migrating to actively maintained alternatives like `http-errors` (note: different package from the same organization) or `http-error-classes`, which offer modern features and better maintenance.

gotcha The package is CommonJS-only and does not natively support ES module `import` syntax. Attempting to use `import httpErrors from 'httperrors';` will lead to runtime errors in a pure ESM environment. ↓

fix Ensure you are using `const httpErrors = require('httperrors');` in your Node.js application. If you must use ESM, you might need to use dynamic `import()` or explore CommonJS-ESM interoperability solutions, though migrating to a modern, ESM-first HTTP error library is recommended.

gotcha There are no official TypeScript type definitions shipped with this package, nor is there an `@types/httperrors` package. ↓

fix Developers using TypeScript will need to create their own declaration files (`.d.ts`) for `httperrors` or use a different, type-safe HTTP error library.

Install

npm install httperrors

yarn add httperrors

pnpm add httperrors

Imports

httpErrors
wrong
```
import httpErrors from 'httperrors';
```
correct
```
const httpErrors = require('httperrors');
```
This package is CommonJS-only and does not support ES module `import` syntax. Attempting to import it in an ESM context will result in an `ERR_REQUIRE_ESM` error.
httpErrors.NotFound
wrong
```
import { NotFound } from 'httperrors';
```
correct
```
const { NotFound } = require('httperrors');
const notFoundError = new NotFound('Item not found');
```
Individual error classes like `NotFound` are properties of the main `httpErrors` object and are accessed via destructuring `require` or `httpErrors.<ClassName>`. Direct ESM imports are not supported.

Quickstart

Demonstrates how to import `httperrors`, instantiate errors by status code and named classes, and perform type-checking in a `try...catch` block.

const httpErrors = require('httperrors');

function handleRequest(resourceExists) {
  if (!resourceExists) {
    // Instantiate by status code
    const notFoundByCode = httpErrors(404, 'The requested resource was not found.');
    console.log(`Error (by code): ${notFoundByCode.statusCode} - ${notFoundByCode.message} (Is 404? ${notFoundByCode[404]})`);
    // Or by name
    const notFoundByName = new httpErrors.NotFound('The item you are looking for does not exist.');
    console.log(`Error (by name): ${notFoundByName.statusCode} - ${notFoundByName.message} (Is NotFound? ${notFoundByName.NotFound})`);
    throw notFoundByName;
  }
  console.log('Resource found and processed.');
}

try {
  handleRequest(false);
} catch (err) {
  if (err.NotFound) {
    console.error(`Caught NotFound error: ${err.message}. Status: ${err.statusCode}`);
  } else if (err.BadGateway) {
    console.error(`Caught BadGateway error: ${err.message}`);
  } else {
    console.error(`Caught unexpected error: ${err.name} - ${err.message}`);
  }
}

// Example of creating other errors
const teapotError = new httpErrors.ImATeapot('I am a teapot, indeed.');
console.log(`Custom error: ${teapotError.message} (Status: ${teapotError.statusCode})`);