HTTP Common

HTTP status code constants and typed error classes for TypeScript. Provides a complete set of named constants for standard HTTP status codes and a hierarchy of error classes that map directly to 4xx and 5xx responses.

Requirements

• Node.js >= 22.0.0

Installation

yarn add @pawells/http-common

Quick Start

import {
	HTTP_STATUS_OK,
	HTTP_STATUS_NOT_FOUND,
	HTTPNotFoundError,
	GetHTTPErrorClass,
} from '@pawells/http-common';

// Use a status constant
console.log(HTTP_STATUS_OK); // 200

// Throw a typed HTTP error
throw new HTTPNotFoundError('User not found');

// Look up an error class by status code
const ErrorClass = GetHTTPErrorClass(404);
if (ErrorClass) {
	throw new ErrorClass('Resource not found');
}

API Reference

Status Constants

All constants are typed as number and named in SCREAMING_SNAKE_CASE.

1xx Informational

| Constant | Value | |---|---| | HTTP_STATUS_CONTINUE | 100 | | HTTP_STATUS_SWITCHING_PROTOCOLS | 101 | | HTTP_STATUS_PROCESSING | 102 | | HTTP_STATUS_EARLY_HINTS | 103 |

2xx Success

| Constant | Value | |---|---| | HTTP_STATUS_OK | 200 | | HTTP_STATUS_CREATED | 201 | | HTTP_STATUS_ACCEPTED | 202 | | HTTP_STATUS_NO_CONTENT | 204 | | HTTP_STATUS_PARTIAL_CONTENT | 206 |

3xx Redirection

| Constant | Value | |---|---| | HTTP_STATUS_MULTIPLE_CHOICES | 300 | | HTTP_STATUS_MOVED_PERMANENTLY | 301 | | HTTP_STATUS_FOUND | 302 | | HTTP_STATUS_NOT_MODIFIED | 304 | | HTTP_STATUS_TEMPORARY_REDIRECT | 307 | | HTTP_STATUS_PERMANENT_REDIRECT | 308 |

4xx Client Errors

| Constant | Value | |---|---| | HTTP_STATUS_BAD_REQUEST | 400 | | HTTP_STATUS_UNAUTHORIZED | 401 | | HTTP_STATUS_FORBIDDEN | 403 | | HTTP_STATUS_NOT_FOUND | 404 | | HTTP_STATUS_METHOD_NOT_ALLOWED | 405 | | HTTP_STATUS_CONFLICT | 409 | | HTTP_STATUS_UNPROCESSABLE_ENTITY | 422 | | HTTP_STATUS_TOO_MANY_REQUESTS | 429 |

5xx Server Errors

| Constant | Value | |---|---| | HTTP_STATUS_INTERNAL_SERVER_ERROR | 500 | | HTTP_STATUS_NOT_IMPLEMENTED | 501 | | HTTP_STATUS_BAD_GATEWAY | 502 | | HTTP_STATUS_SERVICE_UNAVAILABLE | 503 | | HTTP_STATUS_GATEWAY_TIMEOUT | 504 |

Error Classes

All error classes extend HTTPError, which extends BaseError from @pawells/typescript-common. Every constructor accepts a message: string and an optional options: { cause?: Error } for error chaining.

Base Class

| Class | Description | |---|---| | HTTPError | Base class for all HTTP errors. Exposes a read-only statusCode: number property. Constructed with (message, code, statusCode, options?). |

4xx Client Error Classes

| Class | Status | |---|---| | HTTPBadRequestError | 400 | | HTTPUnauthorizedError | 401 | | HTTPForbiddenError | 403 | | HTTPNotFoundError | 404 | | HTTPMethodNotAllowedError | 405 | | HTTPConflictError | 409 | | HTTPUnprocessableEntityError | 422 | | HTTPTooManyRequestsError | 429 |

5xx Server Error Classes

| Class | Status | |---|---| | HTTPInternalServerError | 500 | | HTTPNotImplementedError | 501 | | HTTPBadGatewayError | 502 | | HTTPServiceUnavailableError | 503 | | HTTPGatewayTimeoutError | 504 |

Utility Function

| Export | Signature | Description | |---|---|---| | GetHTTPErrorClass | (statusCode: number) => typeof HTTPError \| null | Returns the error class constructor for a given status code, or null for non-error codes (1xx–3xx) and unmapped codes. |

License

MIT — See LICENSE for details.