HTTP Statuses Utility

2.0.2 · active · verified Sun Apr 19

The `statuses` package provides a comprehensive utility for working with HTTP status codes and messages in Node.js environments. It consolidates status information from official sources like the IANA Status Code Registry, as well as common implementations from the Node.js, NGINX, and Apache HTTP Server projects. Currently at stable version 2.0.2, the library maintains a steady release cadence focused on stability, minor updates, and continuous integration improvements rather than frequent feature additions, reflecting its role as a mature, low-level building block. Its key differentiator lies in its comprehensive data source aggregation and direct mapping capabilities, allowing developers to easily convert between numeric codes and descriptive messages, and access properties like whether a status indicates an empty body, a redirect, or a retryable condition. Unlike some HTTP utilities, `statuses` will throw an error for unknown codes or messages, ensuring strict adherence to recognized HTTP semantics.

Common errors

```
Error: Unknown status code: 306
```
cause Attempting to retrieve the message for the deprecated HTTP status code 306.

fix The 306 status code is not supported. Use recognized HTTP status codes. Wrap lookups in a try-catch if codes are dynamic.
```
Error: Unknown status message: foo
```
cause Attempting to retrieve a status code for a message string that is not a known HTTP status message.

fix Ensure the status message string is a valid, recognized HTTP status message (e.g., 'Forbidden', 'Not Found'). Wrap lookups in a try-catch if messages are dynamic.
```
TypeError: Cannot read properties of undefined (reading 'codes') or similar when using named import for properties like 'codes'
```
cause Trying to import a property (like 'codes' or 'message') directly as a named export from the module in an ESM context.

fix Import the default export first, then access its properties: `import status from 'statuses'; console.log(status.codes);`

Warnings

gotcha Calling the main `status` function with an unknown numeric code or string message will throw an error, rather than returning `undefined` or `null`. This enforces strict adherence to recognized HTTP statuses.
Fix: Always wrap calls to `status()` with a `try...catch` block if user-provided input might result in an unknown code or message, or pre-validate input against `status.codes` or `status.message`.
gotcha The HTTP status code `306` ('Switch Proxy') is deprecated by IANA and not supported by this utility. Attempting to look up `status(306)` will result in an error.
Fix: Avoid using status code 306. If encountered, handle it as an exceptional case or map it to a supported redirect code if appropriate.
gotcha When using ESM `import` syntax, remember that `statuses` exports a default function. Properties like `codes` or `message` are attached to this function. Attempting to use named imports (e.g., `import { codes } from 'statuses';`) will likely fail or result in `undefined`.
Fix: For ESM, import the default export (e.g., `import status from 'statuses';`) and then access its properties (e.g., `status.codes`).

Install

npm install statuses npm
yarn add statuses yarn
pnpm add statuses pnpm

Imports

status
wrong:
```
import { status } from 'statuses';
```
correct:
```
const status = require('statuses');
```
The primary export is a function that acts as a lookup. For CommonJS, use direct require. For ESM, it can typically be imported as a default: `import status from 'statuses';`
status.codes
wrong:
```
import { codes } from 'statuses';
```
correct:
```
const status = require('statuses');
const allCodes = status.codes;
```
The `codes` array is a property on the default exported `status` function, not a named export itself. Access it via the main status object.
status.message
wrong:
```
import { message } from 'statuses';
```
correct:
```
const status = require('statuses');
const msg = status.message[404];
```
The `message` object is a property on the default exported `status` function, providing a direct map from code to message, similar to Node.js' `http.STATUS_CODES`.

Quickstart

Demonstrates core functionality including code-to-message and message-to-code lookups, accessing status code lists and properties like `empty` and `redirect`, and error handling for unknown values.

const status = require('statuses');

// Get message from a numeric status code
console.log('Status 403:', status(403));
console.log('Status "403":', status('403'));

// Get code from a status message (case-insensitive)
console.log('Code for "forbidden":', status('forbidden'));
console.log('Code for "Not Found":', status('Not Found'));

// Access all known status codes
console.log('All status codes (first 5):', status.codes.slice(0, 5));

// Check if a status code expects an empty body
console.log('Does 200 expect empty body?', !!status.empty[200]);
console.log('Does 204 expect empty body?', !!status.empty[204]);

// Check if a status code is a redirect
console.log('Is 200 a redirect?', !!status.redirect[200]);
console.log('Is 301 a redirect?', !!status.redirect[301]);

// Get message directly from the message object
console.log('Message for 404:', status.message[404]);

// Error handling for unknown values
try {
    status(306);
} catch (e) {
    console.error('Error for status(306):', e.message);
}

try {
    status('foo');
} catch (e) {
    console.error('Error for status("foo"):', e.message);
}

view raw JSON →