AnvilJSON utilities

Anvil › Docs › /v1/http-status

HTTP status code API: what 404, 429, 502 and every other code means

Ask for one code with the path form GET /v1/http-status/404 (or the query twin ?code=404) and get a plain-English answer: phrase, category (1xx–5xx), a short summary, when_you_see_it, what_to_do, related cousins, whether retrying can help, and whether caches may store it by default. Ask for a whole class (4xx) or search by name (too many / teapot), or leave the code out for the compact catalogue. Ties into Wirebook's status-code lesson.

In one line: GET /v1/http-status returns JSON. No key, CORS on, 60 requests a minute.
GET

/v1/http-status

Look up any HTTP status code: meaning, causes, fixes and retry advice. Change the values and press Send request to call the live API.



Parameters
NameTypeWhat it doesDefault
codestringA code like 404, a class like 5xx, or words from a name like 'too many'. Leave out for the full list. Path form /v1/http-status/{code} also works.—


Example
Request:
GET https://api.oddlathe.com/v1/http-status


Response (generated by the real code when these docs were last built):
{
 "count": 71,
 "classes": [
  {
   "class": "1xx",
   "category": "1xx informational",
   "name": "Informational",
   "description": "The request was received and the process is continuing.",
   "codes": [
    {
     "code": 100,
     "phrase": "Continue",
     "name": "Continue",
     "category": "1xx informational",
     "class": "Informational",
     "standard": true,
     "spec": "RFC 9110",
     "summary": "The server got the request headers and the client may send the body.",
     "meaning": "The server got the request headers and the client may send the body."
    },
    {
     "code": 101,
     "phrase": "Switching Protocols",
     "name": "Switching Protocols",
     "category": "1xx informational",
     "class": "Informational",
     "standard": true,
     "spec": "RFC 9110",
     "summary": "The server is switching to the protocol the client asked for in Upgrade.",
     "meaning": "The server is switching to the protocol the client asked for in Upgrade."
    },
    {
     "code": 102,
     "phrase": "Processing",
     "name": "Processing",
     "category": "1xx informational",
 …


Code examples
curl
curl 'https://api.oddlathe.com/v1/http-status'
JavaScript (browser or Node 18+)
const res = await fetch("https://api.oddlathe.com/v1/http-status");
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data);
Python (standard library only)
import json, urllib.parse, urllib.request

url = "https://api.oddlathe.com/v1/http-status"
# Send a User-Agent: the edge network refuses Python's default one.
req = urllib.request.Request(url, headers={"User-Agent": "my-script/1.0"})
with urllib.request.urlopen(req, timeout=10) as r:
    data = json.load(r)
print(data)


When it's useful
  • Friendlier error messages in your own app or CLI (map the code to <code>summary</code> / <code>what_to_do</code>)
  • Deciding in a retry loop whether to try again (<code>retryable</code>: no, yes, after or maybe)
  • Chat bots and help desks that explain error pages to people
  • Teaching what the codes mean alongside Wirebook <code>/codes</code>


Good to know
  • Path and query forms return the same JSON. Prefer /v1/http-status/{code} when the code is already a path segment.
  • category is one of 1xx informational, 2xx success, 3xx redirect, 4xx client, 5xx server. phrase is the official reason phrase (Not Found, I'm a teapot…).
  • related lists a few cousins people confuse (for example 401↔403, 502↔503↔504, Cloudflare 52x).
  • retryable is after for 429 and 503: wait for the Retry-After header. yes codes (408, 502, 504, Cloudflare 52x…) are usually temporary; back off exponentially with some jitter.
  • An unregistered code in range, such as 299, returns registered: false and the x00 code it should be treated as, which is how HTTP clients handle unknown codes.
  • cacheable_by_default marks the codes a cache may store without explicit freshness headers (200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414 and 501).
  • Non-standard codes carry standard: false and name who uses them, for example nginx or Cloudflare. Where a Tooltern deep-dive exists, the response includes a guide URL.


Covers every registered code plus the non-standard ones people actually meet (nginx 444/499 and Cloudflare 520–526). Prefer GET /v1/http-status/404 or ?code=404. Each answer includes phrase, category, plain summary, when_you_see_it, what_to_do, related codes, retry advice and default cacheability.


Errors
Errors are JSON like {"error": {"code": "…", "message": "…"}}. The ones this endpoint can return:
  • bad_param (400): a value is the wrong type or out of range (the message says which)
  • rate_limited (429): over 60 requests a minute; wait for Retry-After seconds


Questions
What's the difference between 401 and 403?
401 means the server doesn't know who you are, so signing in may help. 403 means it knows (or doesn't care) and still says no.
Path or query — which should I use?
Same answer either way. Use /v1/http-status/502 when the code is in the path; use ?code=502 (or words like teapot) when you are building a form.
Why does nginx show 499?
499 is logged by nginx when the client hung up before the response was ready. The browser never receives it.
Is 418 real?
It began as a 1998 April Fools' joke about teapots. The code is now reserved so it will never get a serious meaning.


Related endpoints


Prefer a page to an API?


Published , updated  · OpenAPI 3.1 spec · Limits and privacy