# @master4n/http-status > HTTP status code registry & lookup — machine-readable metadata for every HTTP status code (IANA, Cloudflare, Nginx), for apps and AI agents. Latest version **2.0.3** (published 2026-06-21) · MIT license · 0 weekly downloads ## Install ```sh npm install @master4n/http-status pnpm add @master4n/http-status yarn add @master4n/http-status bun add @master4n/http-status ``` ## Health **Score 60/100 (C)** — status: active. Positive: has types; esm support; no vulnerabilities; high maintenance score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 2.0.3 | | Published | 2026-06-21 | | First published | 2023-12-22 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=20 | | Dependencies | 0 | | Unpacked size | 317.5 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Author | master4n | | Maintainers | master4novice | | Keywords | http, http-status, status-codes, iana, cloudflare, nginx, ai-agents, rag, llm, rest-api, type-safe, tree-shaking, http-status-codes, status-code-lookup, http-response-codes, status-code-metadata, rest-api-errors | ## Links - npm: https://www.npmjs.com/package/@master4n/http-status - Repository: https://github.com/Master4Novice/http-status - Homepage: https://github.com/Master4Novice/http-status#readme - Issues: https://github.com/Master4Novice/http-status/issues - npm.io page: https://npm.io/package/@master4n/http-status ## Alternatives - [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads - [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads - [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads - [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads - [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads ## Recent versions - 2.0.3 (latest) — 2026-06-21 - 1.1.2 (legacy) — 2026-05-28 - 2.0.2 — 2026-06-06 - 2.0.1 — 2026-05-31 - 2.0.0 — 2026-05-28 - 1.1.1 — 2024-07-31 - 1.1.0 — 2024-07-12 - 1.0.9 — 2024-07-04 - 1.0.8 — 2024-03-09 - 1.0.7 — 2024-03-09 - 1.0.6 — 2024-01-13 - 1.0.5 — 2023-12-28 - 1.0.3 — 2023-12-27 - 1.0.2 — 2023-12-23 - 1.0.1 — 2023-12-22 - … 1 more at https://npm.io/package/@master4n/http-status/versions ## README # @master4n/http-status [![CI](https://github.com/Master4Novice/http-status/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Master4Novice/http-status/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/%40master4n%2Fhttp-status)](https://www.npmjs.com/package/@master4n/http-status) ![License](https://img.shields.io/npm/l/%40master4n%2Fhttp-status) ![Downloads](https://img.shields.io/npm/dm/%40master4n%2Fhttp-status) ![Owner](https://img.shields.io/badge/Owner-Master4Novice-orange?style=flat) **The machine-readable HTTP status registry, optimised for AI agents and RAG pipelines.** Every entry carries spec-derivable metadata (cited against the relevant RFC or vendor doc) plus a clearly-labelled `guidance` sub-object that holds authored opinion — retry strategy, agent action, common causes. Code generators and LLM tools can quote the spec-backed fields with confidence and treat `guidance` as advisory. --- ## For AI agents - **Static JSON registry (no install required):** - https://unpkg.com/@master4n/http-status@2/http-status-registry.json - https://cdn.jsdelivr.net/npm/@master4n/http-status@2/http-status-registry.json - **Discovery file:** https://unpkg.com/@master4n/http-status@2/llms.txt - **Subpath imports:** `@master4n/http-status/iana`, `/cloudflare`, `/nginx`, `/utils`. - **Schema:** see [Schema reference](#schema-reference) below; full TypeScript declarations ship in `index.d.ts`. > The `guidance` sub-object on every entry is authored opinion, not spec. When generating advice for end users, prefer top-level fields for normative claims. --- ## Installation ```sh npm install @master4n/http-status ``` Zero runtime dependencies. Dual ESM/CommonJS builds. Tree-shakable via per-vendor sub-paths. --- ## Quickstart ```ts import { IanaStatus, IanaRegistry } from '@master4n/http-status/iana'; import { isRetryable, hasEmptyBody } from '@master4n/http-status/utils'; // Status code constants IanaStatus.TOO_MANY_REQUESTS; // 429 IanaStatus.OK; // 200 // Full metadata const meta = IanaRegistry[429]; meta.phrase; // "Too Many Requests" meta.rfc; // "RFC6585" meta.specUrl; // "https://datatracker.ietf.org/doc/html/rfc6585#section-4" meta.guidance.retryStrategy; // "respect-retry-after" meta.guidance.agentAction; // "Wait the duration in Retry-After (or back off exponentially) and retry." // Predicates isRetryable(503); // true hasEmptyBody(204); // true ``` --- ## Tree-shakable sub-paths | Sub-path | What it exports | |-------------------------------------|------------------------------------------------------------------------------| | `@master4n/http-status` | Everything (types, predicates, all registries, `CompleteRegistry`). | | `@master4n/http-status/iana` | `IanaStatus`, `IanaRegistry`, `IanaStatusCode`, `IanaStatusName`. | | `@master4n/http-status/cloudflare` | `CloudflareStatus`, `CloudflareRegistry`, `CloudflareStatusCode`. | | `@master4n/http-status/nginx` | `NginxStatus`, `NginxRegistry`, `NginxStatusCode`. | | `@master4n/http-status/utils` | Pure predicates only (no registry data). For `getMetadata`, import from the root. | | `@master4n/http-status/registry.json` | The full pre-built JSON registry. | --- ## Predicate cookbook ```ts import { isInformational, isSuccess, isRedirection, isClientError, isServerError, isError, isRetryable, hasEmptyBody, isCacheable, requiresAuth, } from '@master4n/http-status/utils'; import { getMetadata } from '@master4n/http-status'; // Retry decision with respect-Retry-After semantics async function fetchWithRetry(url: string, attempts = 3): Promise { const res = await fetch(url); if (res.ok || !isRetryable(res.status) || attempts <= 0) return res; const meta = getMetadata(res.status); const retryAfter = res.headers.get('Retry-After'); const delayMs = meta?.guidance.retryStrategy === 'respect-retry-after' && retryAfter ? Number(retryAfter) * 1000 : 2 ** (3 - attempts) * 500; await new Promise((r) => setTimeout(r, delayMs)); return fetchWithRetry(url, attempts - 1); } ``` --- ## Schema reference Every entry in every registry conforms to `HttpStatusMetadata`: ```ts interface HttpStatusMetadata { // Spec-derivable, cited against `specUrl` code: number; phrase: string; category: 'Informational' | 'Success' | 'Redirection' | 'Client Error' | 'Server Error' | 'Vendor Extension'; source: 'IANA' | 'Cloudflare' | 'Nginx'; rfc: string | null; // e.g. "RFC9110" specUrl: string; // citation URL description: string; expectsEmptyBody: boolean; // RFC 9110: body MUST be empty cacheability: 'heuristic' | 'uncacheable'; // RFC 9111 §4.2.2 (was `isCacheable` in ≤2.0.0) requiresAuth: boolean; safeForMethods: HttpMethod[] | 'all'; relatedHeaders: { name: string; required: boolean; purpose: string }[]; aliases: string[]; deprecated: boolean; // Authored guidance — NOT spec. Treat as recommendation. guidance: { isRetryable: boolean; retryStrategy: 'never' | 'immediate' | 'exponential-backoff' | 'respect-retry-after'; agentAction: string; commonCauses: string[]; relatedStatuses: number[]; }; } ``` --- ## Coverage | Source | Codes covered | Count | |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------| | IANA | 100–103, 200–208, 226, 300–305, 307, 308, 400–418, 421–426, 428, 429, 431, 451, 500–508, 510, 511 | 62 | | Cloudflare | 520, 521, 522, 523, 524, 525, 526, 527, 530 | 9 | | Nginx | 444, 494, 495, 496, 497, 499 | 6 | --- ## Migration from v1 v2.0.0 is a hard break. The v1 `HttpStatus` class is gone. See [CHANGELOG.md](./CHANGELOG.md) for the one-to-one mapping. The new API gives you full metadata in exchange for the rename. ```ts // v1 HttpStatus.OK.value; // 200 HttpStatus.OK.name; // 'OK' HttpStatus.valueOf(200); // ['OK'] // v2 IanaStatus.OK; // 200 IanaRegistry[200].phrase; // 'OK' IanaRegistry[200]; // full metadata (RFC, retry strategy, agent action, …) ``` --- ## Part of the @master4n toolkit A small ecosystem of focused, agent-friendly packages: - [`@master4n/temporal-transformer`](https://www.npmjs.com/package/@master4n/temporal-transformer) — epoch/timestamp ↔ date conversion with auto unit-detection and IANA timezones (Luxon-backed) - [`@master4n/temporal-transformer-codemod`](https://www.npmjs.com/package/@master4n/temporal-transformer-codemod) — codemod to migrate temporal-transformer v1→v2 - [`@master4n/decorators`](https://www.npmjs.com/package/@master4n/decorators) — zero-dependency TypeScript decorators (DI, validation, resilience, redaction) - [`@master4n/master-cli`](https://www.npmjs.com/package/@master4n/master-cli) — headless, JSON-first dev CLI (`mfn`) for humans and AI agents ## License MIT © Master4Novice --- _Source: https://npm.io/package/@master4n/http-status · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._