HTTP Status Codes Constants

Common errors

• TypeError: (0, http_status_codes_1.getStatusText) is not a function

  cause Attempting to use the `getStatusText` function from version 1.x with `http-status-codes` version 2.x or newer.
  fix Rename `getStatusText` to `getReasonPhrase`. Example: `import { getReasonPhrase } from 'http-status-codes';`

• TypeError: Cannot read properties of undefined (reading 'OK') at Object.<anonymous>

  cause This typically occurs when trying to `require` named exports (e.g., `StatusCodes.OK`) in a CommonJS module in a way that doesn't correctly resolve the export, or when a bundler has misconfigured ESM/CJS interop. Alternatively, it can happen if `StatusCodes` itself is not properly imported.
  fix For CommonJS, use `const { StatusCodes } = require('http-status-codes');` or `const StatusCodes = require('http-status-codes').StatusCodes;`. For ESM, ensure `import { StatusCodes } from 'http-status-codes';` is used.

• TS2305: Module ''http-status-codes'' has no exported member 'default'.

  cause Attempting to import a default export (e.g., `import StatusCodes from 'http-status-codes'`) when the library primarily uses named exports. While v2.1.2 added a default export for specific backward compatibility, the primary intended usage is named imports.
  fix Use named imports: `import { StatusCodes } from 'http-status-codes';`.

Warnings

• breaking The function `getStatusText` was renamed to `getReasonPhrase` in version 2.0.0. Code using `getStatusText` will break.
  Fix: Replace all instances of `getStatusText` with `getReasonPhrase`.
• breaking The reason phrase for `500 Internal Server Error` was corrected from 'Server Error' to 'Internal Server Error' in v2.0.0. If you were relying on the exact string 'Server Error', your comparisons might fail.
  Fix: Update any logic that checks for the `500` reason phrase to use `ReasonPhrases.INTERNAL_SERVER_ERROR` or the string 'Internal Server Error'.
• gotcha The library was rewritten in TypeScript starting from v2.0.0, introducing TypeScript enums for `StatusCodes` and `ReasonPhrases`. While this improves type safety, it also means that projects not using TypeScript might notice internal structure changes, though the public API is largely consistent apart from explicit breaking changes.
  Fix: Ensure your build setup correctly handles TypeScript declarations if you are consuming this library in a non-TypeScript project or an older TypeScript environment.
• gotcha From v2.1.4, significant tree-shaking improvements were introduced. Older versions (pre-2.1.4) might result in larger bundle sizes, especially if only a subset of constants is used.
  Fix: Upgrade to `http-status-codes@2.1.4` or newer to benefit from improved tree-shaking and reduced bundle sizes.

Install

• npm install http-status-codes npm
• yarn add http-status-codes yarn
• pnpm add http-status-codes pnpm

Imports

• StatusCodes
  wrong:

  const StatusCodes = require('http-status-codes').StatusCodes;

  correct:

  import { StatusCodes } from 'http-status-codes';

  Since v2.0.0, the primary usage is named imports, particularly with TypeScript enums. CommonJS `require` is supported but named imports are generally preferred for tree-shaking and modern module systems.
• ReasonPhrases
  wrong:

  const ReasonPhrases = require('http-status-codes').ReasonPhrases;

  correct:

  import { ReasonPhrases } from 'http-status-codes';

  Provides human-readable reason phrases. Prior to v2.0.0, these were part of a different API (e.g., via `getStatusText`).
• getReasonPhrase
  wrong:

  import { getStatusText } from 'http-status-codes';

  correct:

  import { getReasonPhrase } from 'http-status-codes';

  The function was renamed from `getStatusText` to `getReasonPhrase` in v2.0.0 for API consistency. Using `getStatusText` will result in an error on v2.0.0 and later.
• getStatusCode
  wrong:

  import { getCode } from 'http-status-codes';

  correct:

  import { getStatusCode } from 'http-status-codes';

  This function was added in v1.4.0. It retrieves a status code from its reason phrase string.

Quickstart

Demonstrates importing and using status code constants, reason phrases, and utility functions to manage HTTP responses.

import { StatusCodes, ReasonPhrases, getReasonPhrase, getStatusCode } from 'http-status-codes';

// Example usage with a hypothetical 'response' object (e.g., from Express)
const response = {
  _status: 200,
  _data: '',
  status(code) {
    this._status = code;
    return this;
  },
  send(data) {
    this._data = data;
    console.log(`Status: ${this._status}, Body: ${JSON.stringify(this._data)}`);
  }
};

// Send a successful response
response
  .status(StatusCodes.OK)
  .send(ReasonPhrases.OK);

// Handle an internal server error
response
  .status(StatusCodes.INTERNAL_SERVER_ERROR)
  .send({
    error: getReasonPhrase(StatusCodes.INTERNAL_SERVER_ERROR)
  });

// Get status code from a reason phrase string
const codeFromPhrase = getStatusCode('Bad Request');
response
  .status(codeFromPhrase)
  .send({
    error: 'An unknown error occurred.'
  });