npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

node-http-status

v1.3.0

Published

Simple and intuitive HTTP response status codes

Readme

npm version npm downloads license

A simple and intuitive HTTP response status code library for Node.js.

Why choose node-http-status?

Zero dependencies. Zero runtime overhead. Just plain objects.

Simple: No complex APIs to learn - just import and use
Lightweight: Under 3KB minified, zero dependencies
Flexible: Multiple access patterns (camelCase, UPPERCASE, numeric)
Customizable: Create your own response object format with createCustomHttpStatus
Localized: Built-in support for multiple languages (EN, JA, ES, DE)
TypeScript-first: Full type safety out of the box
Framework-agnostic: Works with Express, Fastify, Next.js, or any Node.js app

Installation

npm install node-http-status

Usage

ES Modules (Recommended)

import httpStatus from 'node-http-status'

// Get status information - multiple ways to access the same response
console.log(httpStatus.ok)
console.log(httpStatus.OK)        // UPPERCASE alias
console.log(httpStatus[200])      // Numeric alias
// All output: { status: 200, code: 'OK', message: 'The request has succeeded' }

// All three are the same object
console.log(httpStatus.OK === httpStatus.ok === httpStatus[200])
// Output: true

console.log(httpStatus.forbidden)
console.log(httpStatus.FORBIDDEN)
console.log(httpStatus[403])
// All output: { status: 403, code: 'FORBIDDEN', message: 'The server understood the request but refuses to authorize it' }

// Access just the status code
console.log(httpStatus.ok.status)
// Output: 200

// Use in Express.js
app.get('/api/users', (req, res) => {
  const users = getUsersFromDatabase()
  res.status(httpStatus.ok.status).json({
    ...httpStatus.ok,
    data: users
  })
})

// Handle errors
app.get('/api/users/:id', (req, res) => {
  const user = findUser(req.params.id)
  if (!user) {
    return res.status(httpStatus.notFound.status).json(httpStatus.notFound)
  }
  res.json({ ...httpStatus.ok, data: user })
})

CommonJS

// Method 1: Dynamic import (Recommended for newer Node.js versions)
const httpStatus = await import('node-http-status').then(m => m.default)

// Method 2: Require (works with dual exports)
const httpStatus = require('node-http-status')

// Usage is identical to ES modules
console.log(httpStatus.ok)
console.log(httpStatus.OK)        // UPPERCASE alias  
console.log(httpStatus[200])      // Numeric alias
// All output: { status: 200, code: 'OK', message: 'The request has succeeded' }

// Use in Express.js with CommonJS
app.get('/api/users', (req, res) => {
  const users = getUsersFromDatabase()
  res.status(httpStatus.ok.status).json({
    ...httpStatus.ok,
    data: users
  })
})

Note: If you get import errors with CommonJS, ensure:

  • You're using Node.js 18+ (required by this package)
  • Your project doesn't have conflicting module settings
  • Consider using dynamic imports for better compatibility

Available Status Codes

2xx Success

  • ok - 200 OK
  • created - 201 Created
  • accepted - 202 Accepted
  • noContent - 204 No Content
  • partialContent - 206 Partial Content

3xx Redirection

  • moved - 301 Moved Permanently
  • found - 302 Found
  • notModified - 304 Not Modified
  • temporaryRedirect - 307 Temporary Redirect
  • permanentRedirect - 308 Permanent Redirect

4xx Client Error

  • badRequest - 400 Bad Request
  • unauthorized - 401 Unauthorized
  • forbidden - 403 Forbidden
  • notFound - 404 Not Found
  • methodNotAllowed - 405 Method Not Allowed
  • notAcceptable - 406 Not Acceptable
  • requestTimeout - 408 Request Timeout
  • conflict - 409 Conflict
  • gone - 410 Gone
  • lengthRequired - 411 Length Required
  • preconditionFailed - 412 Precondition Failed
  • payloadTooLarge - 413 Payload Too Large
  • uriTooLong - 414 URI Too Long
  • unsupportedMediaType - 415 Unsupported Media Type
  • rangeNotSatisfiable - 416 Range Not Satisfiable
  • expectationFailed - 417 Expectation Failed
  • imATeapot - 418 I'm a teapot
  • unprocessableEntity - 422 Unprocessable Entity
  • upgradeRequired - 426 Upgrade Required
  • preconditionRequired - 428 Precondition Required
  • tooManyRequests - 429 Too Many Requests
  • requestHeaderFieldsTooLarge - 431 Request Header Fields Too Large
  • unavailableForLegalReasons - 451 Unavailable For Legal Reasons

5xx Server Error

  • internalServerError - 500 Internal Server Error
  • notImplemented - 501 Not Implemented
  • badGateway - 502 Bad Gateway
  • serviceUnavailable - 503 Service Unavailable
  • gatewayTimeout - 504 Gateway Timeout
  • httpVersionNotSupported - 505 HTTP Version Not Supported
  • networkAuthenticationRequired - 511 Network Authentication Required

Localization

The library supports multiple languages for status code messages. Import locale-specific versions to get translated messages while keeping the same API.

Available Locales

  • English (default): node-http-status
  • Japanese: node-http-status/locale/ja
  • Spanish: node-http-status/locale/es
  • German: node-http-status/locale/de

Usage

// ES Modules
// Default English
import httpStatus from 'node-http-status'
console.log(httpStatus.FORBIDDEN.message)
// "The server understood the request but refuses to authorize it"

// Japanese
import httpStatus from 'node-http-status/locale/ja'
console.log(httpStatus.FORBIDDEN.message)
// "サーバーはリクエストを理解したが、承認を拒否した。"

// Spanish  
import httpStatus from 'node-http-status/locale/es'
console.log(httpStatus.FORBIDDEN.message)
// "El servidor entendió la solicitud pero se niega a autorizarla"

// German
import httpStatus from 'node-http-status/locale/de'
console.log(httpStatus.FORBIDDEN.message)
// "Der Server verstand die Anfrage, verweigert aber die Autorisierung"
// CommonJS
// Default English
const httpStatus = require('node-http-status')
console.log(httpStatus.FORBIDDEN.message)
// "The server understood the request but refuses to authorize it"

// Japanese
const httpStatus = require('node-http-status/locale/ja')
console.log(httpStatus.FORBIDDEN.message)
// "サーバーはリクエストを理解したが、承認を拒否した。"

// Spanish  
const httpStatus = require('node-http-status/locale/es')
console.log(httpStatus.FORBIDDEN.message)
// "El servidor entendió la solicitud pero se niega a autorizarla"

// German
const httpStatus = require('node-http-status/locale/de')
console.log(httpStatus.FORBIDDEN.message)
// "Der Server verstand die Anfrage, verweigert aber die Autorisierung"

Locale API

Each locale provides the exact same API as the default English version:

import httpStatus from 'node-http-status/locale/ja'

// All access patterns work the same
console.log(httpStatus.forbidden.message)  // camelCase
console.log(httpStatus.FORBIDDEN.message)  // UPPERCASE  
console.log(httpStatus[403].message)       // numeric

// Status codes and code names remain unchanged
console.log(httpStatus.FORBIDDEN.status)  // 403
console.log(httpStatus.FORBIDDEN.code)    // "FORBIDDEN"

Express.js with Locales

import express from 'express'
import httpStatus from 'node-http-status/locale/es'

const app = express()

app.get('/api/data', (req, res) => {
  // Send Spanish error messages to Spanish-speaking users
  res.status(httpStatus.notFound.status).json(httpStatus.notFound)
  // Response: { status: 404, code: 'NOT_FOUND', message: 'No se pudo encontrar el recurso solicitado' }
})

Custom Formatters

Need a different response object structure? Use createCustomHttpStatus to define your own format while keeping all the convenience of aliases and status codes.

import { createCustomHttpStatus } from 'node-http-status'

// Create a custom formatter function
const customHttp = createCustomHttpStatus((status, code, message) => ({
  response: {
    error: code,
    message: message
  },
  statusCode: status
}))

// Use it just like the regular httpStatus object
console.log(customHttp.internalServerError)
// { response: { error: 'INTERNAL_SERVER_ERROR', message: '...' }, statusCode: 500 }

// All aliases work the same way
console.log(customHttp.INTERNAL_SERVER_ERROR === customHttp.internalServerError)  // true
console.log(customHttp[500] === customHttp.internalServerError)                    // true

REST API Format Example

import { createCustomHttpStatus } from 'node-http-status'

const apiFormat = createCustomHttpStatus((status, code, message) => ({
  success: status < 400,
  statusCode: status,
  error: status >= 400 ? {
    type: code,
    message: message
  } : null,
  data: null
}))

// Success response
console.log(apiFormat.ok)
// { success: true, statusCode: 200, error: null, data: null }

// Error response  
console.log(apiFormat.badRequest)
// { success: false, statusCode: 400, error: { type: 'BAD_REQUEST', message: '...' }, data: null }

Express.js with Custom Format

import express from 'express'
import { createCustomHttpStatus } from 'node-http-status'

const app = express()

// Create Express-friendly format
const expressFormat = createCustomHttpStatus((status, code, message) => ({
  status,
  error: {
    code: code,
    detail: message
  }
}))

app.get('/api/users/:id', (req, res) => {
  const user = findUser(req.params.id)
  if (!user) {
    const notFoundResponse = expressFormat.notFound
    return res.status(notFoundResponse.status).json(notFoundResponse.error)
  }
  
  const okResponse = expressFormat.ok
  res.status(okResponse.status).json({ 
    ...okResponse.error, 
    user 
  })
})

TypeScript with Custom Formatters

import { createCustomHttpStatus, type HttpStatusFormatter } from 'node-http-status'

// Define your custom response type
interface CustomResponse {
  httpStatus: number
  errorType: string
  description: string
  timestamp: string
}

// Create type-safe formatter
const formatter: HttpStatusFormatter<CustomResponse> = (status, code, message) => ({
  httpStatus: status,
  errorType: code, 
  description: message,
  timestamp: new Date().toISOString()
})

const customHttp = createCustomHttpStatus(formatter)

// Full type safety
const response: CustomResponse = customHttp.forbidden
// response.httpStatus is number
// response.errorType is string  
// response.description is string
// response.timestamp is string

API Reference

Each status code returns a consistent object structure:

interface HttpStatus {
  status: number;    // The numeric HTTP status code
  code: string;      // The standard HTTP status phrase  
  message: string;   // A human-readable description
}

TypeScript Support

Built with TypeScript and includes complete type definitions out of the box.

// ES Modules
import httpStatus from 'node-http-status'

const response: HttpStatus = httpStatus.ok
// response.status is typed as number
// response.code is typed as string  
// response.message is typed as string

// CommonJS  
const httpStatus = require('node-http-status')
const response: HttpStatus = httpStatus.ok
// Fully typed in both module systems

// The httpStatus object is typed as HttpStatusObject which includes all aliases
const statusHandler = (httpCodes: HttpStatusObject) => {
  console.log(httpCodes.OK === httpCodes.ok === httpCodes[200])  // true
}
statusHandler(httpStatus)

Examples

Express.js API

import express from 'express'
import httpStatus from 'node-http-status'

const app = express()

// Success response
app.get('/health', (req, res) => {
  res.status(httpStatus.ok.status).json({
    ...httpStatus.ok,
    timestamp: new Date().toISOString()
  })
})

// Error handling
app.use((err, req, res, next) => {
  console.error(err)
  res.status(httpStatus.internalServerError.status).json(httpStatus.internalServerError)
})

Fetch API

import httpStatus from 'node-http-status'

const response = await fetch('/api/data')

if (response.status === httpStatus.notFound.status) {
  console.log('Resource not found')
} else if (response.status === httpStatus.ok.status) {
  const data = await response.json()
  // Handle success
}

License

MIT