What it does
Every HTTP response starts with a three-digit status code that tells the client how the request went. The first digit gives the class: 1xx informational, 2xx success, 3xx redirection, 4xx the client made a mistake, 5xx the server failed.
Codes people often mix up
- 401 vs 403: 401 means "who are you?" (not authenticated); 403 means "I know who you are, and the answer is no".
- 301 vs 302: 301 is permanent and 302 is temporary; search engines use the difference as a hint about which URL to keep. 307 and 308 are the same ideas but never change the HTTP method.
- 502, 503 and 504: a bad response from upstream, an overloaded or offline server, and an upstream that took too long.
Codes 520-526 are not part of the HTTP standard: Cloudflare uses them to describe problems reaching your origin server.
Choosing a code for an API or a page
- 200, 201, 204: 200 returns a body, 201 says something was created, and 204 succeeds with no body, as after a DELETE.
- 400 vs 422: 400 is for a request that is malformed, 422 for one that is well formed but fails validation. Many APIs use only 400; what matters is being consistent.
- 304: the answer to a conditional request, such as one with
If-None-Match. The client keeps using its cached copy. - 401, 405 and 429: a 401 should come with a
WWW-Authenticateheader, a 405 withAllow, and a 429 can carryRetry-After.
These headers can be read in the HTTP Header Analyzer. To see the real status line of a request, run it with curl -i; the cURL Command Generator builds the command. When a redirect response sends you to a new address, the URL Parser splits the Location value into its parts.
Often-confused codes
- 401 and 403. 401 Unauthorized means the request has no valid credentials, so logging in may help. 403 Forbidden means that the server understood who you are and still refuses.
- 301, 302, 307 and 308. 301 and 308 are permanent redirects, 302 and 307 are temporary. 307 and 308 keep the original method, for example POST, while older clients may change it to GET for 301 and 302.
- 500, 502, 503 and 504. 500 is an error inside the server. 502 means a gateway received an invalid answer from the server behind it, 503 means the service is temporarily unavailable, and 504 means the gateway waited too long.
- 429 Too Many Requests. The client is being rate limited. A Retry-After header may say when to try again.
- 418 I’m a teapot. A joke status from the 1998 April Fools’ RFC 2324, which some APIs use deliberately.
To look at the headers that came with a response, use the HTTP Header Analyzer, and to build a request, use the cURL Command Generator.
Frequently asked questions
What do the code ranges mean?
1xx are informational, 2xx mean success, 3xx are redirects, 4xx are client errors and 5xx are server errors.
Which code should my API return when a record is not found?
404 Not Found. Use 400 for a request that is badly formed and 422 for data that is well formed but fails validation.
How do I find a code quickly?
Type a number or a word in the search box, for example “redirect”, which shows 301, 302, 303, 307 and 308, or use the class filter. The list has 69 codes, each with a plain-English meaning.
Privacy
This tool runs entirely in your browser. What you enter is processed on your device and is not sent to a server.