Package Exports

http-fault

Readme

http-fault

A lightweight, framework-agnostic TypeScript library for creating and handling structured HTTP exceptions.

Features

Full 4xx/5xx coverage — one class per HTTP status code
Structured responses — consistent JSON shape across every error
Framework agnostic — works with Express, Fastify, Koa, Hono, raw node:http, or anything built on it
Safe by default — 5xx details are hidden from clients unless explicitly exposed
Extensible — create domain-specific exceptions by extending any class
Zero dependencies — only uses node:http built-in types

Installation

npm install http-fault

File Structure

http.exception.ts        # Abstract base class
http.exceptions.ts       # All 4xx and 5xx exception classes
exception-filter.ts      # Framework-agnostic error handler

Quick Start

import { NotFoundException } from "http-fault";

throw new NotFoundException({ message: "User not found." });

Every error is serialized to a consistent JSON response:

{
  "status": 404,
  "error": "Not Found",
  "message": "User not found.",
  "code": undefined,
  "details": undefined,
  "path": "/users/99",
  "timestamp": "2026-02-28T12:00:00.000Z"
}

HttpException Base Class

All exceptions extend HttpException, which extends Error.

abstract class HttpException extends Error {
  readonly status: number; // HTTP status code
  readonly error: string; // Standard HTTP error name
  readonly message: string; // Human-readable description (inherited from Error)
  readonly code?: string; // Optional machine-readable error code
  readonly details?: unknown; // Optional structured payload
  readonly expose: boolean; // Whether details are safe to send to the client
  readonly cause?: Error; // Optional originating error
}

Constructor Options

All exception constructors accept an optional options object:

Option	Type	Description
`message`	`string`	Human-readable description. Defaults to the HTTP error name.
`code`	`string`	Machine-readable error code (e.g. `"USER_NOT_FOUND"`).
`details`	`unknown`	Structured payload (e.g. validation errors).
`expose`	`boolean`	Whether `message` and `details` reach the client. Auto-set: `true` for 4xx, `false` for 5xx.
`cause`	`Error`	The originating error, for error chaining.

Built-in Exceptions

4xx Client Errors

Class	Status
`BadRequestException`	400
`UnauthorizedException`	401
`PaymentRequiredException`	402
`ForbiddenException`	403
`NotFoundException`	404
`MethodNotAllowedException`	405
`NotAcceptableException`	406
`ProxyAuthenticationRequiredException`	407
`RequestTimeoutException`	408
`ConflictException`	409
`GoneException`	410
`LengthRequiredException`	411
`PreconditionFailedException`	412
`ContentTooLargeException`	413
`URITooLongException`	414
`UnsupportedMediaTypeException`	415
`RangeNotSatisfiableException`	416
`ExpectationFailedException`	417
`ImATeapotException`	418
`MisdirectedRequestException`	421
`UnprocessableEntityException`	422
`LockedException`	423
`FailedDependencyException`	424
`TooEarlyException`	425
`UpgradeRequiredException`	426
`PreconditionRequiredException`	428
`TooManyRequestsException`	429
`RequestHeaderFieldsTooLargeException`	431
`UnavailableForLegalReasonsException`	451

5xx Server Errors

Class	Status
`InternalServerErrorException`	500
`NotImplementedException`	501
`BadGatewayException`	502
`ServiceUnavailableException`	503
`GatewayTimeoutException`	504
`HTTPVersionNotSupportedException`	505
`VariantAlsoNegotiatesException`	506
`InsufficientStorageException`	507
`LoopDetectedException`	508
`NotExtendedException`	510
`NetworkAuthenticationRequiredException`	511

Throwing Exceptions

import {
  NotFoundException,
  ForbiddenException,
  UnprocessableEntityException,
  ConflictException,
} from "http-fault";

// Minimal — just a status
throw new NotFoundException();

// With a message
throw new NotFoundException({ message: "User 42 not found." });

// With a machine-readable code
throw new ForbiddenException({
  message: "Only admins can perform this action.",
  code: "INSUFFICIENT_ROLE",
});

// With structured details (great for validation errors)
throw new UnprocessableEntityException({
  message: "Validation failed.",
  code: "VALIDATION_FAILED",
  details: {
    email: ["Must be a valid email address."],
    age: ["Must be at least 18."],
  },
});

// With error chaining
try {
  await db.insert(user);
} catch (cause) {
  throw new ConflictException({
    message: "A user with this email already exists.",
    code: "EMAIL_TAKEN",
    cause,
  });
}

Custom Exceptions

Extend any built-in class to create reusable domain exceptions.

import {
  UnauthorizedException,
  TooManyRequestsException,
  HttpException,
} from "http-fault";

// Fix the code and default message for a specific auth scenario
class TokenExpiredException extends UnauthorizedException {
  constructor(cause?: Error) {
    super({
      message: "Your session has expired. Please sign in again.",
      code: "TOKEN_EXPIRED",
      cause,
    });
  }
}

// Carry typed runtime data in details
class QuotaExceededException extends TooManyRequestsException {
  constructor(used: number, limit: number) {
    super({
      message: `Daily quota exceeded (${used}/${limit}).`,
      code: "QUOTA_EXCEEDED",
      details: { used, limit },
    });
  }
}

// Build directly on HttpException for full control
class MaintenanceModeException extends HttpException {
  constructor(until: string) {
    super(503, "Service Unavailable", {
      message: "The service is under scheduled maintenance.",
      code: "MAINTENANCE_MODE",
      details: { until },
      expose: true, // safe to surface despite being 5xx
    });
  }
}

// Usage
throw new TokenExpiredException();
throw new QuotaExceededException(1000, 1000);
throw new MaintenanceModeException("2026-03-01T06:00:00Z");

ExceptionFilter

The ExceptionFilter converts any thrown value into a structured JSON response. It handles both HttpException instances and unexpected raw errors.

API

// One-off call
ExceptionFilter(err, req, res, options?)

// Pre-configured factory — bind options once, reuse everywhere
const handleError = createExceptionFilter(options?)
handleError(err, req, res)

Options

Option	Type	Description
`onError`	`(err, response) => void`	Custom logger. Called for all errors if provided, or only 5xx by default.
`resolvePath`	`(req) => string`	Override how the request path is extracted. Defaults to `req.url ?? "/"`.
`forceHideDetails`	`boolean`	Always hide `message` and `details`, regardless of `expose`. Useful in tests.

Integrations

Raw Node.js

import http from "node:http";
import { ExceptionFilter } from "http-fault";

http
  .createServer(async (req, res) => {
    try {
      await router(req, res);
    } catch (err) {
      ExceptionFilter(err, req, res);
    }
  })
  .listen(3000);

Express

import express from "express";
import { ExceptionFilter } from "http-fault";

const app = express();

app.get("/users/:id", (req, res) => {
  throw new NotFoundException({ message: `User ${req.params.id} not found.` });
});

// Register last
app.use((err, req, res, _next) => ExceptionFilter(err, req, res));

Fastify

import Fastify from "fastify";
import { ExceptionFilter } from "http-fault";

const fastify = Fastify();

fastify.setErrorHandler((err, req, reply) => {
  ExceptionFilter(err, req.raw, reply.raw);
});

Koa

import Koa from "koa";
import { ExceptionFilter } from "http-fault";

const app = new Koa();

app.on("error", (err, ctx) => {
  ExceptionFilter(err, ctx.req, ctx.res);
});

Custom Logger

import pino from "pino";
import { createExceptionFilter } from "http-fault";

const logger = pino();

export const handleError = createExceptionFilter({
  onError: (err, response) => {
    if (response.status >= 500) {
      logger.error({ err, response }, "Unhandled server error");
    } else {
      logger.warn({ response }, "Client error");
    }
  },
});

// app.use((err, req, res, _next) => handleError(err, req, res));

The `expose` Flag

This flag controls whether message and details are sent to the client.

Scenario	`expose` default	What the client sees
4xx exception	`true`	Full `message` and `details`
5xx exception	`false`	Only the standard HTTP error name
Custom exception	Your choice	Depends on `expose` option

// Client receives the full message and details (expose: true by default for 4xx)
throw new UnprocessableEntityException({
  message: "Email is invalid.",
  details: { field: "email" },
});
// → { message: "Email is invalid.", details: { field: "email" }, ... }

// Client receives only "Internal Server Error" (expose: false by default for 5xx)
throw new InternalServerErrorException({
  message: "Database connection lost at 192.168.1.5:5432",
});
// → { message: "Internal Server Error", details: undefined, ... }

// Force-expose a 5xx (use with care)
throw new ServiceUnavailableException({
  message: "Back online at 03:00 UTC.",
  expose: true,
});
// → { message: "Back online at 03:00 UTC.", ... }

Error Response Shape

Every error response follows this structure:

{
  status: number       // HTTP status code
  error: string        // Standard HTTP error name
  message: string      // Human-readable description (gated by expose)
  code?: string        // Machine-readable code (gated by expose)
  details?: unknown    // Structured payload (gated by expose)
  path: string         // Request path
  timestamp: string    // ISO 8601 timestamp
}

Testing

serializeException is a pure function — no server required.

import { serializeException, NotFoundException } from "http-fault";

it("returns 404 with message and code", () => {
  const err = new NotFoundException({
    message: "Post not found.",
    code: "POST_NOT_FOUND",
  });

  const result = serializeException(err, "/posts/99");

  expect(result).toMatchObject({
    status: 404,
    error: "Not Found",
    message: "Post not found.",
    code: "POST_NOT_FOUND",
    path: "/posts/99",
  });
});

it("hides details when forceHideDetails is true", () => {
  const err = new NotFoundException({ message: "Hidden." });
  const result = serializeException(err, "/", true);

  expect(result.message).toBe("Not Found"); // message hidden
  expect(result.details).toBeUndefined();
});

it("maps unknown errors to 500", () => {
  const result = serializeException(new Error("boom"), "/");
  expect(result.status).toBe(500);
});

License

MIT

http-fault

Package Exports

Readme

http-fault

Features

Installation

File Structure

Quick Start

HttpException Base Class

Constructor Options

Built-in Exceptions

4xx Client Errors

5xx Server Errors

Throwing Exceptions

Custom Exceptions

ExceptionFilter

API

Options

Integrations

Custom Logger

The expose Flag

Error Response Shape

Testing

License

The `expose` Flag