@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

See Also