HTTP Status Codes Utility

Common errors

• TypeError: require(...) is not a function or is undefined

  cause Attempting to use `require('http-status')` as a direct function call or expecting it to return the default export directly after the v2 migration for CommonJS.
  fix Update CommonJS import: `const { default: status } = require('http-status');` or `const status = require('http-status').default;`.

• SyntaxError: Named export 'NOT_FOUND' not found. The requested module 'http-status' does not provide an export named 'NOT_FOUND'

  cause Incorrectly trying to destructure a named export in an ESM context when the module primarily offers a default export for the main `status` object.
  fix If you want the main `status` object, use `import status from 'http-status';`. If you truly want a named export, ensure it's specifically exported (e.g., `OK_CODE` or `NOT_FOUND` are indeed named exports, so `import { NOT_FOUND } from 'http-status'` is correct). This error often implies confusion between default and named exports.

Warnings

• breaking Version 2.x migrated the library to ESM modules and TypeScript. While the API remains largely the same, CommonJS `require` statements need to be updated to access the default export correctly.
  Fix: For CommonJS, use `const { default: status } = require('http-status');` or `const status = require('http-status').default;`. For named exports, `const { NOT_FOUND } = require('http-status');` is correct.
• gotcha The package includes `_NAME`, `_MESSAGE`, and `_CLASS` suffixes for accessing specific attributes of a status code (e.g., `status[404_NAME]`, `status.NOT_FOUND_MESSAGE`). For the primary status code message, the code name itself is sufficient (e.g., `status.NOT_FOUND` returns 'Not Found').
  Fix: Understand the API structure: `status[CODE]` gives the name, `status.NAME` gives the message, `status.NAME_CODE` gives the number. `status[CODE_NAME]` and `status[CODE_MESSAGE]` provide explicit access to the name and message respectively, similar to `status.NAME` and `status.NAME_CODE`.
• gotcha When accessing 'extra' status codes, they are nested under `status.extra.<category>` (e.g., `status.extra.cloudflare`). Direct top-level access to these non-standard codes is not available unless explicitly imported from a sub-path.
  Fix: To access specific extra codes, use `status.extra.cloudflare[520]` or `status.extra.nginx.NO_RESPONSE_CODE`. Alternatively, `import extraStatus from 'http-status/extra/cloudflare'` allows direct access to those codes, which are merged with common HTTP statuses in the imported object.

Install

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

Imports

• status
  wrong:

  import { status } from 'http-status'

  correct:

  import status from 'http-status'

  For ESM, `status` is the default export. While `import { status }` also works due to dual export, the default is typically preferred.
• status
  wrong:

  const status = require('http-status')

  correct:

  const { default: status } = require('http-status')

  Since v2, for CommonJS, the default export is accessed via `default` property. `require('http-status')` directly returns an object with the default export under the `default` key, among others. `const { status } = require('http-status')` is also common and recommended for named access.
• status
  wrong:

  import status.NOT_FOUND from 'http-status'

  correct:

  import { NOT_FOUND, OK_CODE } from 'http-status'

  Individual status code constants (like `NOT_FOUND` or `OK_CODE`) are directly exported as named exports for convenience.
• status
  wrong:

  import { cloudflare } from 'http-status'

  correct:

  import status from 'http-status/extra/cloudflare'

  Specific categories of 'extra' status codes can be imported directly as default exports from their respective paths. This merges them with regular statuses.

Quickstart

Demonstrates how to retrieve HTTP status code names, messages, and classes by both numeric code and symbolic name, including access to 'extra' status codes and class metadata.

import status from 'http-status';

console.log('--- Standard HTTP Status Codes ---');
// Look up status message by code
console.log('200 Name:', status[200_NAME]); // Outputs: OK
console.log('404 Message:', status[404_MESSAGE]); // Outputs: Not Found
console.log('500 Class:', status[500_CLASS]); // Outputs: SERVER_ERROR

// Look up code or message by status name
console.log('OK Code:', status.OK_CODE); // Outputs: 200
console.log('IM_A_TEAPOT Message:', status.IM_A_TEAPOT); // Outputs: I'm a teapot

console.log('\n--- Status Code Classes ---');
// Access status code classes
console.log('1xx Class Name:', status.classes[1].name); // Outputs: Informational
console.log('2xx Message:', status.classes.SUCCESSFUL_MESSAGE); // Outputs: Successful

console.log('\n--- Extra Status Codes (Cloudflare) ---');
// Access extra status codes via `extra` property
console.log('Cloudflare 520:', status.extra.cloudflare[520_MESSAGE]); // Outputs: Unknown Error
console.log('Cloudflare NO_RESPONSE Code:', status.extra.cloudflare.NO_RESPONSE_CODE); // Outputs: 444

// Example of directly importing extra codes (requires separate import statement or direct require)
// import cloudflareStatus from 'http-status/extra/cloudflare';
// console.log('Cloudflare 522 Message:', cloudflareStatus[522_MESSAGE]);