@b9g/http-errors

HTTP error classes for consistent error handling.

HTTPError

Base class for all HTTP errors.

Constructor

new HTTPError(status: number, message?: string, options?: HTTPErrorOptions)

HTTPErrorOptions

interface HTTPErrorOptions {
  cause?: Error;
  headers?: Record<string, string>;
  expose?: boolean;
}

Properties

Property	Type	Description
`status`	`number`	HTTP status code
`statusCode`	`number`	Alias for `status`
`message`	`string`	Error message
`expose`	`boolean`	Expose message to clients
`headers`	`Record<string, string>`	Custom headers
`cause`	`Error`	Original error

toJSON(): object

Serializes the error.

error.toJSON();
// { name, message, status, statusCode, expose }

toResponse(isDev?: boolean): Response

Converts to HTTP Response.

error.toResponse();      // Plain text
error.toResponse(true);  // HTML with stack trace

Client Errors (4xx)

Class	Status	Default Message
`BadRequest`	400	Bad Request
`Unauthorized`	401	Unauthorized
`Forbidden`	403	Forbidden
`NotFound`	404	Not Found
`MethodNotAllowed`	405	Method Not Allowed
`Conflict`	409	Conflict
`UnprocessableEntity`	422	Unprocessable Entity
`TooManyRequests`	429	Too Many Requests

Server Errors (5xx)

Class	Status	Default Message
`InternalServerError`	500	Internal Server Error
`NotImplemented`	501	Not Implemented
`BadGateway`	502	Bad Gateway
`ServiceUnavailable`	503	Service Unavailable
`GatewayTimeout`	504	Gateway Timeout

isHTTPError(value: unknown): value is HTTPError

Type guard for HTTP errors.

if (isHTTPError(error)) {
  console.log(error.status);
}

Usage

import { NotFound, BadRequest } from "@b9g/http-errors";

throw new NotFound("User not found");

throw new BadRequest("Invalid email", {
  headers: { "X-Error-Code": "INVALID_EMAIL" },
});

Exposure

4xx errors expose messages by default; 5xx errors don't.

throw new BadRequest("Invalid input");  // Exposed
throw new InternalServerError("DB failed");  // Hidden

throw new InternalServerError("Overloaded", { expose: true });  // Override

API