Guide
Choosing HTTP status codes and returning errors as problem details
The status line of an HTTP response is the first thing every client, cache, proxy and monitoring tool reads. Picking the right code makes an API predictable; picking the wrong one produces retry storms, cached errors and confused developers. This reference lists every registered code with plain explanations, and builds the standard error body that modern APIs return alongside them.
The five classes
The first digit sets the class. 1xx codes are informational, such as 101 Switching Protocols for WebSockets and 103 Early Hints. 2xx means success: 200 OK, 201 Created, 204 No Content. 3xx redirects the client elsewhere or says to use its cache. 4xx means the request was wrong, and 5xx means the server failed. The class matters more than the exact code, because clients are required to fall back to it.
Codes people confuse
401 Unauthorized really means unauthenticated: credentials are missing or invalid, and logging in may fix it. 403 Forbidden means the server knows who you are and refuses. 404 hides or lacks a resource, 410 says it is gone for good. 400 is for malformed requests, 422 for well-formed requests with invalid content, and 409 for conflicts with current state, such as a duplicate. 502 is a bad answer from an upstream server, 503 means temporarily unavailable, and 504 means the upstream timed out.
Redirects and methods
Four redirect codes cover permanent and temporary moves with or without method preservation. 301 and 302 allow clients to change POST to GET; 307 and 308 forbid it. 303 See Other tells the client to fetch the result with GET, the pattern after a form submission. 304 Not Modified is not a redirect but the answer to a conditional request, telling the client to use its cached copy. 405 Method Not Allowed must include an Allow header.
Using the list
Type a number or a word, such as 429 or rate limit, or filter by class. Each card shows the code, name, defining RFC and a one-sentence meaning. Registered codes come from RFC 9110 and the other HTTP RFCs: WebDAV adds 207 to 208 and 422 to 424, RFC 6585 added 428, 429, 431 and 511, and RFC 8470 added 425.
Problem details
RFC 9457, which replaced RFC 7807, defines a JSON error format with the media type application/problem+json. type is a URI that identifies the kind of problem (or about:blank when the status says it all), title is a short summary that stays the same for every occurrence, status repeats the HTTP status, detail explains this occurrence and instance identifies it. Extra members may add machine-readable data such as a balance or a list of invalid fields.
A worked example
Searching 429 finds Too Many Requests. “Build an error body” opens the builder with status 429, title “Too Many Requests” and type about:blank; adding the extension member {"balance":30} gives a body whose keys appear in the order type, title, status, detail, instance and balance. The panel also prints an Express call that sends it with the right content type, and a JSON download.
Retry and caching behaviour
Clients may retry 408, 429, 502, 503 and 504 safely for idempotent requests, ideally after the delay in Retry-After. 404, 405, 410 and 301 can be cached by default, which is a reason to be careful with them. 5xx errors should not be cached unless you set explicit headers.
Limits
The page is a reference, not a validator for your API. Some servers add non-standard codes, such as 499 in Nginx and 520 to 527 at Cloudflare, which are not listed because they are not in the IANA registry.
Related tools
- Redirect Generator writes 301, 302, 307 and 308 rules for servers.
- MIME Type Lookup covers the Content-Type side of responses.
- Rate Limit Simulator models when 429 responses occur.
- cURL to Code turns a request that returns an error into code.
Checked against the current version of the HTTP Status Codes on .