Registry / http-networking / throw-http-errors

throw-http-errors

library4.0.1jsnpmunverified

throw-http-errors is a JavaScript/TypeScript library designed to streamline the creation and handling of HTTP status code-specific errors. Currently at version 4.0.1, the library provides a comprehensive set of custom error classes corresponding to most standard HTTP status codes, from client errors like `BadRequest` (400) and `Unauthorized` (401) to server errors such as `InternalServerError` (500) and `ServiceUnavailable` (503). It allows developers to instantiate these errors either by their descriptive named class (e.g., `new errors.NotFound('User not found')`) or by their numeric status code (e.g., `new errors[404]('Resource missing')`), along with optional custom messages and internal error codes, providing flexibility for different error reporting needs. The library also includes a `CreateCustomError` utility for defining unique application-specific HTTP errors. This package differentiates itself by offering a structured, type-safe approach to HTTP error propagation in modern Node.js and browser environments, shipping with full TypeScript definitions to enhance developer experience and reduce runtime errors. While a previous JavaScript-only version exists on a separate branch (pre-v4), the current major version prioritizes TypeScript and ESM, ensuring a modern and robust error handling mechanism for web applications and APIs. The project maintains a steady release cadence, with major versions typically indicating significant architectural or language-level shifts.

http-networking web-framework serialization

npm install throw-http-errors

github ↗package ↗

INSTALL

IMPORT

SIG · THROW-HTTP-ERRORS

throw-http-errors

http-networkingjavascriptv4.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

BadRequest

✓ import { BadRequest } from 'throw-http-errors';

✗ import BadRequest from 'throw-http-errors';

This is the preferred way to import individual HTTP error constructors in modern ESM projects and TypeScript.

errors

✓ import * as errors from 'throw-http-errors';

✗ const errors = require('throw-http-errors');

Use this namespace import to access all error constructors (e.g., `errors.NotFound` or `errors[404]`) in ESM projects. The CommonJS `require` pattern is typically for older Node.js environments.

errors

✓ const errors = require('throw-http-errors');

✗ import errors from 'throw-http-errors';

This CommonJS `require` pattern is supported for legacy Node.js projects, but for modern ESM, `import * as errors from 'throw-http-errors';` is recommended, especially in v4+.

Demonstrates how to create and catch various HTTP-specific errors, including custom ones, within a simulated API request function. It shows instantiation by named classes and how to handle them polymorphically using `instanceof HttpError`.

import { BadRequest, NotFound, InternalServerError, CreateCustomError, HttpError } from 'throw-http-errors'; // Define a custom application-specific error with a specific status code const TooManyRequestsFromUser = CreateCustomError(429, 'TooManyRequestsFromUser', 'Too many requests from this user ID', 1002); function simulateApiRequest(userId: string, data: any): { success: boolean; message?: string } { try { if (!userId) { // Throw an error by class name throw new BadRequest('User ID is required.', 1001); } if (userId === 'blocked_user') { // Throw a custom error throw new TooManyRequestsFromUser(); } if (data.id === 'nonexistent') { // Throw an error by status code number throw new NotFound('Resource with provided ID not found.', 1003); } // Simulate an unexpected server error if (Math.random() < 0.1) { throw new InternalServerError('An unexpected database error occurred.', 5000); } return { success: true, message: `Request processed for user ${userId}.` }; } catch (error) { if (error instanceof HttpError) { console.error(`HTTP Error (${error.statusCode} - ${error.name}): ${error.message} (Code: ${error.code})`); return { success: false, message: `Failed: ${error.message}` }; } else if (error instanceof Error) { console.error(`Generic Error: ${error.message}`); return { success: false, message: `An unknown error occurred: ${error.message}` }; } throw error; // Re-throw if not an Error instance } } console.log(simulateApiRequest('', { id: 'test' })); // Should throw BadRequest console.log(simulateApiRequest('test_user', {})); // Should succeed or throw InternalServerError randomly console.log(simulateApiRequest('blocked_user', { id: 'valid' })); // Should throw TooManyRequestsFromUser console.log(simulateApiRequest('another_user', { id: 'nonexistent' })); // Should throw NotFound console.log(simulateApiRequest('admin_user', { id: 'secret' })); // Should succeed or throw InternalServerError randomly

Debug

Known issues

breakingVersion 4.0.0 introduced a significant shift to a TypeScript-first, ESM-oriented codebase. Projects previously relying on CommonJS `require()` might encounter issues, especially in environments that do not transpile or bundle ESM correctly, or if explicit module specifiers are not used.

fix

For ESM projects, use `import { ErrorName } from 'throw-http-errors';` or `import * as errors from 'throw-http-errors';`. For CommonJS projects, ensure your build setup correctly handles ESM modules, or consider sticking to a pre-v4 version if a full migration to ESM imports is not feasible.

affects: >=4.0.0

gotchaThe main `errors` object exported by the library (whether through CommonJS `require` or ESM namespace import) is a collection of error constructors, not a constructor itself. Attempting to instantiate `new errors()` will result in a TypeError.

fix

Always instantiate specific error classes, e.g., `new errors.NotFound()` or `new errors[404]()`, or import them individually as named exports like `new NotFound()`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: errors is not a constructor

Attempting to instantiate the `errors` object directly instead of a specific HTTP error class.

fix

Use `new errors.BadRequest()` or `new errors[400]()` to create specific HTTP error instances, or import and instantiate individual error classes like `new BadRequest()`.

ReferenceError: require is not defined

Attempting to use CommonJS `require` syntax in an ECMAScript Module (ESM) project, especially in Node.js environments configured for ESM (`"type": "module"` in `package.json`) or in modern browsers.

fix

Migrate your imports to ESM syntax: `import { BadRequest } from 'throw-http-errors';` or `import * as errors from 'throw-http-errors';`.

TypeError: (0 , _throw_http_errors.BadRequest) is not a constructor

This often occurs in bundled or transpiled projects when there's a mismatch between how CommonJS modules are imported into an ESM context, or incorrect default/named export handling during bundling.

fix

Ensure your bundler (e.g., Webpack, Rollup, Parcel) or TypeScript configuration (`esModuleInterop`, `allowSyntheticDefaultImports`) is correctly set up to handle module interop. If using TypeScript, set `"esModuleInterop": true` in your `tsconfig.json`. Always explicitly import named exports: `import { BadRequest } from 'throw-http-errors';`.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/eldimious/throw-error ↗

packagehttps://www.npmjs.com/package/throw-http-errors ↗