{"id":12076,"library":"statuses","title":"HTTP Statuses Utility","description":"The `statuses` package provides a comprehensive utility for working with HTTP status codes and messages in Node.js environments. It consolidates status information from official sources like the IANA Status Code Registry, as well as common implementations from the Node.js, NGINX, and Apache HTTP Server projects. Currently at stable version 2.0.2, the library maintains a steady release cadence focused on stability, minor updates, and continuous integration improvements rather than frequent feature additions, reflecting its role as a mature, low-level building block. Its key differentiator lies in its comprehensive data source aggregation and direct mapping capabilities, allowing developers to easily convert between numeric codes and descriptive messages, and access properties like whether a status indicates an empty body, a redirect, or a retryable condition. Unlike some HTTP utilities, `statuses` will throw an error for unknown codes or messages, ensuring strict adherence to recognized HTTP semantics.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/jshttp/statuses","tags":["javascript","http","status","code"],"install":[{"cmd":"npm install statuses","lang":"bash","label":"npm"},{"cmd":"yarn add statuses","lang":"bash","label":"yarn"},{"cmd":"pnpm add statuses","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary export is a function that acts as a lookup. For CommonJS, use direct require. For ESM, it can typically be imported as a default: `import status from 'statuses';`","wrong":"import { status } from 'statuses';","symbol":"status","correct":"const status = require('statuses');"},{"note":"The `codes` array is a property on the default exported `status` function, not a named export itself. Access it via the main status object.","wrong":"import { codes } from 'statuses';","symbol":"status.codes","correct":"const status = require('statuses');\nconst allCodes = status.codes;"},{"note":"The `message` object is a property on the default exported `status` function, providing a direct map from code to message, similar to Node.js' `http.STATUS_CODES`.","wrong":"import { message } from 'statuses';","symbol":"status.message","correct":"const status = require('statuses');\nconst msg = status.message[404];"}],"quickstart":{"code":"const status = require('statuses');\n\n// Get message from a numeric status code\nconsole.log('Status 403:', status(403));\nconsole.log('Status \"403\":', status('403'));\n\n// Get code from a status message (case-insensitive)\nconsole.log('Code for \"forbidden\":', status('forbidden'));\nconsole.log('Code for \"Not Found\":', status('Not Found'));\n\n// Access all known status codes\nconsole.log('All status codes (first 5):', status.codes.slice(0, 5));\n\n// Check if a status code expects an empty body\nconsole.log('Does 200 expect empty body?', !!status.empty[200]);\nconsole.log('Does 204 expect empty body?', !!status.empty[204]);\n\n// Check if a status code is a redirect\nconsole.log('Is 200 a redirect?', !!status.redirect[200]);\nconsole.log('Is 301 a redirect?', !!status.redirect[301]);\n\n// Get message directly from the message object\nconsole.log('Message for 404:', status.message[404]);\n\n// Error handling for unknown values\ntry {\n    status(306);\n} catch (e) {\n    console.error('Error for status(306):', e.message);\n}\n\ntry {\n    status('foo');\n} catch (e) {\n    console.error('Error for status(\"foo\"):', e.message);\n}","lang":"javascript","description":"Demonstrates core functionality including code-to-message and message-to-code lookups, accessing status code lists and properties like `empty` and `redirect`, and error handling for unknown values."},"warnings":[{"fix":"Always wrap calls to `status()` with a `try...catch` block if user-provided input might result in an unknown code or message, or pre-validate input against `status.codes` or `status.message`.","message":"Calling the main `status` function with an unknown numeric code or string message will throw an error, rather than returning `undefined` or `null`. This enforces strict adherence to recognized HTTP statuses.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid using status code 306. If encountered, handle it as an exceptional case or map it to a supported redirect code if appropriate.","message":"The HTTP status code `306` ('Switch Proxy') is deprecated by IANA and not supported by this utility. Attempting to look up `status(306)` will result in an error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For ESM, import the default export (e.g., `import status from 'statuses';`) and then access its properties (e.g., `status.codes`).","message":"When using ESM `import` syntax, remember that `statuses` exports a default function. Properties like `codes` or `message` are attached to this function. Attempting to use named imports (e.g., `import { codes } from 'statuses';`) will likely fail or result in `undefined`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"The 306 status code is not supported. Use recognized HTTP status codes. Wrap lookups in a try-catch if codes are dynamic.","cause":"Attempting to retrieve the message for the deprecated HTTP status code 306.","error":"Error: Unknown status code: 306"},{"fix":"Ensure the status message string is a valid, recognized HTTP status message (e.g., 'Forbidden', 'Not Found'). Wrap lookups in a try-catch if messages are dynamic.","cause":"Attempting to retrieve a status code for a message string that is not a known HTTP status message.","error":"Error: Unknown status message: foo"},{"fix":"Import the default export first, then access its properties: `import status from 'statuses'; console.log(status.codes);`","cause":"Trying to import a property (like 'codes' or 'message') directly as a named export from the module in an ESM context.","error":"TypeError: Cannot read properties of undefined (reading 'codes') or similar when using named import for properties like 'codes'"}],"ecosystem":"npm"}