node-http-status


> 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

``bash
npm install node-http-status
`

Usage

$3


`javascript
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 })
})
`

$3


`javascript
// 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

$3


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

$3

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

$3

- 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

$3

- 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.

$3

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

$3

`javascript
// 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"
`

`javascript
// 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"
`

$3

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

`javascript
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"
`

$3

`javascript
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.

`javascript
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
`

$3

`javascript
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 }
`

$3

`javascript
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
})
})
`

$3

`typescript
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 = (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:

`typescript
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.

`typescript
// 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

$3

`javascript
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)
})
`

$3

`javascript
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