Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

http-status

adaltas2.6mBSD-3-Clause2.1.0TypeScript support: included

Interact with HTTP status code

http, connect, frontend, status, express

readme

HTTP Status codes for Node.js

Utility to interact with HTTP status codes.

Migration to v2.x

Version 2 is a migration of the library to ESM modules and TypeScript. The API remains the same. The build system generates both ESM and CommonJS exports.

For ESM users, the import remains the same.

import status from "http-status";
// Or
import { status } from "http-status";

For CommonJs users, update the require statement.

const { status } = require("http-status");
// Or
const { default: status } = require("http-status");

Usage

Once you import or require this module, you may call it with either an HTTP code or a status name. With an HTTP code, you will get the status name while with a status name you will get an HTTP code or some complementary information.

For example, status[418] return IM_A_TEAPOT while status.IM_A_TEAPOT return "I'm a teapot" and status.IM_A_TEAPOT_CODE returns 418.

The package is written in TypeScript and built for CommonJS and ESM.

HTTP Status codes

HTTP code names, information, and classes are respectively accessible with the property {code}_NAME, {code}_MESSAGE and {code}_CLASS. This includes all statuses in the IANA HTTP Status Code Registry, with the only addition being 418 I'm a teapot.

Extra codes

Extra status code are also made available that are not defined in the IANA registry, but used by popular softwares. They are grouped by category. Specific properties are exported by http-status under the property extra followed by the category name. Also, extra codes are merge with regular status codes and made available as modules available inside http-status/lib/{category}.

Available categories are:

unofficial
This represent a list of codes which are not specified by any standard.
iis
Microsoft's Internet Information Services (IIS) web server expands the 4xx error class to signal errors with the client's request.
nginx
The NGINX web server software expands the 4xx error class to signal issues with the client's request.
cloudflare
Cloudflare's reverse proxy service expands the 5xx error class to signal issues with the origin server.

They are accessible throught the status.extra[category] property. It is also possible to import one of the category with import status from "http-status/<category>" orconst status = require("http-status/<category>")`. In the later case, all the categories properties are merge with the common HTTP statuses.

HTTP Status code classes

In addition to HTTP status codes, this module also contains status code classes under the classes property. Similar to HTTP codes, you can access class names and messages with the property {class}_NAME and {class}_MESSAGE.

API organization

The API is structured as follows:

100
100_NAME
100_MESSAGE
100_CLASS
CONTINUE
101
101_NAME
101_MESSAGE
101_CLASS
SWITCHING_PROTOCOLS
…
classes.
├── 1xx
├── 1xx_NAME
├── 1xx_MESSAGE
├── INFORMATIONAL
├── 2xx
├── 2xx_NAME
├── 2xx_MESSAGE
├── SUCCESSFUL
├── …
extra.
├── unofficial.
│   ├── 103
│   ├── 103_NAME
│   ├── 103_MESSAGE
│   ├── 103_CLASS
│   ├── CHECKPOINT
│   ├── …
├── iis.
│   ├── 440
│   ├── 440_NAME
│   ├── 440_MESSAGE
│   ├── 440_CLASS
│   ├── LOGIN_TIME_OUT
│   ├── …
├── nginx.
│   ├── 444
│   ├── 444_NAME
│   ├── 444_MESSAGE
│   ├── 444_CLASS
│   ├── NO_RESPONSE
│   ├── …
├── cloudflare.
│   ├── 520
│   ├── 520_NAME
│   ├── 520_MESSAGE
│   ├── 520_CLASS
│   ├── UNKNOWN_ERROR
│   ├── …

For additional information, please refer to original code.

Example API usage

The api example illustrate how to access status names by code and number and how to extra various associated informations.

import status from "http-status";

console.info(status.INTERNAL_SERVER_ERROR);
// Output: 500

console.info(status[500]);
console.info(status[status.INTERNAL_SERVER_ERROR]);
// Both output: "Internal Server Error"

console.info(status["500_NAME"]);
console.info(status[`${status.INTERNAL_SERVER_ERROR}_NAME`]);
// Both output: "INTERNAL_SERVER_ERROR"

console.info(status["500_MESSAGE"]);
console.info(status[`${status.INTERNAL_SERVER_ERROR}_MESSAGE`]);
// Both output: "A generic error message, given when an unexpected condition was encountered and no more specific message is suitable."

console.info(status["500_CLASS"]);
console.info(status[`${status.INTERNAL_SERVER_ERROR}_CLASS`]);
// Both output: "5xx"

Example using classes

import status from "http-status";

const responseCode = status.INTERNAL_SERVER_ERROR;

switch (status[`${responseCode}_CLASS`]) {
  case status.classes.INFORMATIONAL:
    // The responseCode is 1xx
    break;
  case status.classes.SUCCESSFUL:
    // The responseCode is 2xx
    break;
  case status.classes.REDIRECTION:
    // The responseCode is 3xx
    break;
  case status.classes.CLIENT_ERROR:
    // The responseCode is 4xx
    break;
  case status.classes.SERVER_ERROR:
    // The responseCode is 5xx
    break;

  default:
    // Unknown
    break;
}

Example using the extra property

// Accessing property from the NGINX category
import status from "http-status";
console.info(status.extra.nginx.NO_RESPONSE);

// Accessing default HTTP status merged with NGINX status
import status from "http-status/lib/nginx";
console.info(status.IM_A_TEAPOT);
console.info(status.NO_RESPONSE);

Example integrating Express

The express example integrate the library with a real wold usage.

import express from "express";
import redis from "redis";
import status from "http-status";

// New Express HTTP server
const app = express.createServer();
// Regster a route
app.get("/", (req, res) => {
  const client = redis.createClient();
  client.ping((err, msg) => {
    if (err) {
      return res.send(status.INTERNAL_SERVER_ERROR);
    }
    res.send(msg, status.OK);
  });
});
// Start the HTTP server
app.listen(3000);

Contributors

The project is sponsored by Adaltas based in Paris, France. Adaltas offers support and consulting on distributed systems, big data and open source.

Developers

To automatically generate a new version:

npm run release

Package publication is handled by the CI/CD with GitHub action.

changelog

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

2.1.0 (2025-01-04)

Features

2.0.0 (2024-10-21)

Features

1.8.1 (2024-10-21)

  • Revert changes introduced by 1.8.0

1.7.4 (2024-02-23)

Bug Fixes

  • types: improve TypeScript strict typing for numeric keys in HttpStatus (#49) (4945afd), closes #48

1.7.3 (2023-10-17)

1.7.2 (2023-10-17)

1.7.1 (2023-10-17)

1.7.0 (2023-09-04)

Features

1.6.2 (2023-01-10)

Bug Fixes

  • types: add undefined to types (8efa2e1), closes #43

1.6.1 (2023-01-01)

1.6.0 (2023-01-01)

Features

1.5.3 (2022-09-07)

1.5.2 (2022-05-06)

Bug Fixes

1.5.1 (2022-04-14)

Bug Fixes

  • types: 502 is missing _NAME, _MESSAGE, _CLASS (b86e714)

Version 1.5.0

  • ts: support strict mode
  • mocha: move config into package
  • package: latest dependencies

Version 1.4.2

  • package: update adaltas url

Version 1.4.1

  • readme: fix api example

Version 1.4.0

  • codes: add status code classes

Version 1.3.2

  • 502: wrong key for name and message

Version 1.3.1

  • ts: define properties as readonly

Version 1.3.0

  • codes: new codes 102 and 103
  • ts: rewrite declaration type file
  • ts: mocha integration

Version 1.2.0

  • typescript: use primitives

Version 1.1.2

  • typescript: generate correct typescript definitions file #28

Version 1.1.1

  • codes: double 420 #26
  • codes: wrong keys for 305_MESSAGE and 305_NAME #25
  • typescript: types files
  • package: remove Makefile
  • travis: test against Node.js 6,7,8

Version 1.1.0

  • extra: add unofficial, iis, nginx and cloudflare codes
  • package: publishing process
  • package: ignore lock files
  • src: new code and message properties
  • package: latest dependencies
  • readme: add author company

Version 0.1.1 – Nov 13, 2012

  • Module as a better citizen
  • Makefile to compile and run tests

Version 0.1.1 – Dec 13, 2011

  • Code officially under the BSD License

Version 0.1.0 – April 17, 2011

  • Added reference links to HTTP specification
  • Fixed naming convention for constants from PascalCase to ALL_CAPS
  • Converted status codes from string to number
  • Updated samples
  • Updated tests
  • Added this CHANGELOG

Version 0.0.1 – March 25, 2011

  • Initial release.