Skip to main content

HTTP Status Codes API

REAL DATA

The complete IANA HTTP status code registry with practical descriptions, defining RFCs and a retryable flag — list by category or look up a single code.

Authoritative reference data or standards computation

Base URL
/api/http-statuses
Capabilities
2 routes
Last updated
July 29, 2026
Data sources · 2

GET /api/http-statuses

Live requestRuns against the public API
No key required
GET/api/http-statuses?category=clientError

Request parameters

Only return codes in this class.

Only return codes that are (or are not) sensibly retryable.

Advanced response options6 options

Limit the number of returned records (1–100). Defaults to all matches.

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code samples Ready-to-copy requests in 4 languages
Choose a code sample language
curl "https://randomapi.dev/api/http-statuses?category=clientError"
const res = await fetch("https://randomapi.dev/api/http-statuses?category=clientError");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/http-statuses?category=clientError").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/http-statuses?category=clientError"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 2
category enum

Only return codes in this class.

default: any
allowed: informational | success | redirect | clientError | serverError | any
example: category=clientError
retryable boolean

Only return codes that are (or are not) sensibly retryable.

example: retryable=true
Universal parameters Shared response and formatting options 6
count int

Limit the number of returned records (1–100). Defaults to all matches.

default: all matches
allowed: 1 – 100
example: count=3
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=code,reason
exclude list

Return all fields except these (comma-separated).

example: exclude=retryable
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 6
code integer

The status code.

example: 429

reason string

Reason phrase exactly as registered with IANA. Sole exception: 418 keeps the widely-implemented RFC 2324 phrase "I'm a teapot", which IANA lists as "(Unused)".

example: Too Many Requests

category string

informational | success | redirect | clientError | serverError.

example: clientError

description string

What the code means and when to use it.

example: The client exceeded a rate limit; Retry-After indicates how long to back off.

rfc string

Defining specification, as referenced by the registry — an RFC number for every permanent registration, or the Internet-Draft name for IANA's single temporary one (104).

example: RFC 6585

retryable boolean

Whether retrying the identical request can plausibly succeed.

example: true

Documented examples

Build-generated requests and complete responses
3
All client errors
GET /api/http-statuses?category=clientError
{
  "data": [
    {
      "code": 400,
      "reason": "Bad Request",
      "category": "clientError",
      "description": "The server cannot process the request due to a client error (malformed syntax, invalid parameters).",
      "rfc": "RFC 9110",
      "retryable": false
    },
    {
      "code": 401,
      "reason": "Unauthorized",
      "category": "clientError",
      "description": "Authentication is required or failed; the response includes a WWW-Authenticate challenge.",
      "rfc": "RFC 9110",
      "retryable": false
    },
    {
      "code": 402,
      "reason": "Payment Required",
      "category": "clientError",
      "description": "Reserved for future use; some APIs use it for exhausted quotas or required payment.",
      "rfc": "RFC 9110",
      "retryable": false
    },
    {
      "code": 403,
      "reason": "Forbidden",
      "category": "clientError",
      "description": "The server understood the request but refuses to authorize it; authenticating differently won't help.",
      "rfc": "RFC 9110",
      "retryable": false
    },
    {
      "code": 404,
      "reason": "Not Found",
      "category": "clientError",
      "description": "The server can't find a current representation for the target resource.",
      "rfc": "RFC 9110",
    …
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
Everything retryable
GET /api/http-statuses?retryable=true
{
  "data": [
    {
      "code": 408,
      "reason": "Request Timeout",
      "category": "clientError",
      "description": "The server timed out waiting for the complete request and closed the connection.",
      "rfc": "RFC 9110",
      "retryable": true
    },
    {
      "code": 421,
      "reason": "Misdirected Request",
      "category": "clientError",
      "description": "The request was sent to a server unable to produce an authoritative response (wrong origin).",
      "rfc": "RFC 9110",
      "retryable": true
    },
    {
      "code": 425,
      "reason": "Too Early",
      "category": "clientError",
      "description": "The server refuses to process a request that might be replayed (TLS early data).",
      "rfc": "RFC 8470",
      "retryable": true
    },
    {
      "code": 429,
      "reason": "Too Many Requests",
      "category": "clientError",
      "description": "The client exceeded a rate limit; Retry-After indicates how long to back off.",
      "rfc": "RFC 6585",
      "retryable": true
    },
    {
      "code": 500,
      "reason": "Internal Server Error",
      "category": "serverError",
      "description": "A generic unexpected condition prevented the server from fulfilling the request.",
      "rfc": "RFC 9110",
    …
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
The whole registry as CSV
GET /api/http-statuses?format=csv
code,reason,category,description,rfc,retryable
100,Continue,informational,The initial part of the request was received; the client should continue with the request body.,RFC 9110,false
101,Switching Protocols,informational,The server agrees to switch protocols as requested via the Upgrade header (e.g. to WebSocket).,RFC 9110,false
102,Processing,informational,The server has accepted the full request but has not yet completed it (WebDAV). Deprecated.,RFC 2518,false
103,Early Hints,informational,Preliminary headers (typically Link preload hints) sent before the final response.,RFC 8297,false
104,Upload Resumption Supported,informational,Tells the client the server supports resumable uploads. IANA's only temporary registration: it cites an Internet-Draft rather than an RFC and expires 2026-11-13 unless renewed.,draft-ietf-httpbis-resumable-upload-05,false
200,OK,success,The request succeeded. The meaning of the response body depends on the method used.,RFC 9110,false
201,Created,success,The request succeeded and a new resource was created; its URI is usually in the Location header.,RFC 9110,false
202,Accepted,success,The request was accepted for asynchronous processing that may still fail or be disallowed.,RFC 9110,false
203,Non-Authoritative Information,success,The response was modified by a transforming proxy from the origin's 200 response.,RFC 9110,false
204,No Content,success,The request succeeded and there is intentionally no response body.,RFC 9110,false
205,Reset Content,success,The request succeeded; the client should reset the document view (e.g. clear a form).,RFC 9110,false
206,Partial Content,success,The server is delivering only the byte range(s) requested via the Range header.,RFC 9110,false
207,Multi-Status,success,"Multiple independent sub-responses, conveyed in an XML body (WebDAV).",RFC 4918,false
208,Already Reported,success,Members of a WebDAV binding were already enumerated earlier in the same response.,RFC 5842,false
226,IM Used,success,The response expresses the result of one or more instance manipulations (delta encoding).,RFC 3229,false
300,Multiple Choices,redirect,Several representations exist; the client or user should pick one of the listed alternatives.,RFC 9110,false
301,Moved Permanently,redirect,The resource has a new permanent URI; clients should update links. Method may change to GET.,RFC 9110,false
302,Found,redirect,"The resource temporarily lives at a different URI. Historically, clients switch the method to GET.",RFC 9110,false
303,See Other,redirect,The result is available at another URI and should be retrieved with GET (typical after a POST).,RFC 9110,false
304,Not Modified,redirect,The cached representation is still valid; no body is sent (conditional GET).,RFC 9110,false
305,Use Proxy,redirect,Deprecated: the resource must be accessed through the given proxy.,RFC 9110,false
306,(Unused),redirect,"Reserved. Defined by an earlier revision of the HTTP specification, no longer used, and kept reserved by RFC 9110, Section 15.4.7.",RFC 9110,false
307,Temporary Redirect,redirect,"Like 302, but the method and body must NOT change when following the redirect.",RFC 9110,false
308,Permanent Redirect,redirect,"Like 301, but the method and body must NOT change when following the redirect.",RFC 9110,false
400,Bad Request,clientError,"The server cannot process the request due to a client error (malformed syntax, invalid parameters).",RFC 9110,false
401,Unauthorized,clientError,Authentication is required or failed; the response includes a WWW-Authenticate challenge.,RFC 9110,false
402,Payment Required,clientError,Reserved for future use; some APIs use it for exhausted quotas or required payment.,RFC 9110,false
403,Forbidden,clientError,The server understood the request but refuses to authorize it; authenticating differently won't help.,RFC 9110,false
404,Not Found,clientError,The server can't find a current representation for the target resource.,RFC 9110,false
405,Method Not Allowed,clientError,The method is known but not supported by the target resource; Allow lists the valid methods.,RFC 9110,false
406,Not Acceptable,clientError,"No representation satisfies the content-negotiation headers (Accept, Accept-Language, …).",RFC 9110,false
407,Proxy Authentication Required,clientError,"Like 401, but authentication is required with the proxy instead.",RFC 9110,false
408,Request Timeout,clientError,The server timed out waiting for the complete request and closed the connection.,RFC 9110,true
409,Conflict,clientError,The request conflicts with the current state of the resource (e.g. an edit conflict or duplicate).,RFC 9110,false
410,Gone,clientError,The resource is permanently gone and no forwarding address is known; links should be removed.,RFC 9110,false
411,Length Required,clientError,The server requires a Content-Length header and refuses the request without it.,RFC 9110,false
412,Precondition Failed,clientError,"A conditional header (If-Match, If-Unmodified-Since, …) evaluated to false on the server.",RFC 9110,false
413,Content Too Large,clientError,The request body exceeds what the server is willing or able to process.,RFC 9110,false
414,URI Too Long,clientError,The request target is longer than the server is willing to interpret.,RFC 9110,false510,Not Extended,serverError,Further extensions to the request are required for the server to fulfil it. Marked obsoleted by IANA: RFC 2774 was reclassified Historic.,RFC 2774,false
511,Network Authentication Required,serverError,The client must authenticate with the network (captive portals).,RFC 6585,false

GET /api/http-statuses/lookup

Live requestRuns against the public API
No key required
GET/api/http-statuses/lookup?code=418

Request parameters

The status code to look up.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code samples Ready-to-copy requests in 4 languages
Choose a code sample language
curl "https://randomapi.dev/api/http-statuses/lookup?code=418"
const res = await fetch("https://randomapi.dev/api/http-statuses/lookup?code=418");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/http-statuses/lookup?code=418").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/http-statuses/lookup?code=418"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 1
code int required

The status code to look up.

allowed: 100 – 599
example: code=418
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=code,reason
exclude list

Return all fields except these (comma-separated).

example: exclude=retryable
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 6
code integer

The status code.

example: 429

reason string

Reason phrase exactly as registered with IANA. Sole exception: 418 keeps the widely-implemented RFC 2324 phrase "I'm a teapot", which IANA lists as "(Unused)".

example: Too Many Requests

category string

informational | success | redirect | clientError | serverError.

example: clientError

description string

What the code means and when to use it.

example: The client exceeded a rate limit; Retry-After indicates how long to back off.

rfc string

Defining specification, as referenced by the registry — an RFC number for every permanent registration, or the Internet-Draft name for IANA's single temporary one (104).

example: RFC 6585

retryable boolean

Whether retrying the identical request can plausibly succeed.

example: true

Documented examples

Build-generated requests and complete responses
2
What is 418?
GET /api/http-statuses/lookup?code=418
{
  "data": {
    "code": 418,
    "reason": "I'm a teapot",
    "category": "clientError",
    "description": "April-fools code from RFC 2324's Hyper Text Coffee Pot Control Protocol. IANA lists 418 as \"(Unused)\": per RFC 9110, Section 15.5.19 the joke was deployed often enough to make the code unusable for anything else, so it is reserved rather than assignable.",
    "rfc": "RFC 2324",
    "retryable": false
  },
  "meta": {
    "endpoint": "http-statuses",
    "route": "/lookup",
    "params": {
      "code": 418
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
Is 503 retryable?
GET /api/http-statuses/lookup?code=503&fields=code,reason,retryable
{
  "data": {
    "code": 503,
    "reason": "Service Unavailable",
    "retryable": true
  },
  "meta": {
    "endpoint": "http-statuses",
    "route": "/lookup",
    "params": {
      "code": 503
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}

About this API

Coverage & behavior

All 64 values assigned in the IANA HTTP Status Code Registry — the RFC 9110 core set plus the WebDAV and extension codes — each with its registered reason phrase, a practical description, the defining specification and a retryable flag your error-handling can use directly.

Use the list route to browse a whole class (?category=clientError) or the lookup route as a quick reference (/lookup?code=418). Unknown codes return an explicit 404 — never a guess.

Honest edges, because "registered" is not the same as "usable": IANA lists both 306 and 418 as (Unused) — reserved, not assignable — and 418 keeps its famous RFC 2324 teapot phrase here because that is what implementations actually send; 104 is IANA's only temporary registration and cites an Internet-Draft rather than an RFC; 510 is obsoleted. The registry CSV is pinned by SHA-256 at the 2025-09-15 snapshot and re-verified by a deterministic parity script — nothing is fetched while your request is served.

Use it for

  • Build retry logic from the retryable flag instead of hand-maintained lists
  • Show human-readable error explanations in dashboards and logs
  • Quick terminal reference: curl randomapi.dev/api/http-statuses/lookup?code=503

Frequently asked questions

How do I look up one status code?

/api/http-statuses/lookup?code=418 returns that code's reason phrase, category, description and defining RFC — unknown codes answer an honest 404.

Can I list only one category?

Yes — category filters with the exact values informational, success, redirect, clientError and serverError (matched case-insensitively), and retryable narrows to codes worth retrying.

Is this the official registry?

It is every value IANA has assigned, pinned to the 2025-09-15 registry snapshot by SHA-256 and re-verified by a parity script. The description prose and the retryable flag are our own judgement, not IANA data.

Is 418 I'm a teapot a real status code?

It is in the registry, but reserved rather than assignable: IANA lists 418 as (Unused), and RFC 9110, Section 15.5.19 explains the RFC 2324 joke was deployed often enough to make the code unusable for anything else. This API keeps the teapot phrase because that is what implementations send. 306 is reserved the same way.

Standards & references