What a status code is
Every HTTP response starts with a three-digit number that tells the client how the request went. The client reads that number first and decides what to do next: show the page, follow a redirect, use a cached copy, ask for a password, or report an error.
The number is for machines. Next to it, HTTP/1.1 sends a short reason phrase such as Not Found for humans reading raw traffic. Clients must not depend on the phrase, servers may change it, and HTTP/2 and HTTP/3 drop it entirely and send only the number.
The five classes
The first digit puts every code into one of five groups. A client that meets a code it has never seen should treat it like the x00 code of the same class, so an unknown 299 is handled like 200.
- 1xx Informational: an interim answer sent before the final response.
- 2xx Success: the server received, understood and accepted the request.
- 3xx Redirection: the client must take another step, usually requesting a different URL or reusing its cache.
- 4xx Client error: the request itself is wrong in some way. Sending it again unchanged will usually fail again.
- 5xx Server error: the request may be fine, but the server or something behind it failed to handle it.
Common codes and what they mean
The reason phrases below are the standard ones, taken from the http.HTTPStatus enum in Python's standard library. Note that the current HTTP specification renamed 422 to Unprocessable Content; many libraries still use the older wording.
| Code | Reason phrase | Plain meaning |
|---|---|---|
| 200 | OK | The request worked; the body holds the result. |
| 201 | Created | A new resource was created. |
| 204 | No Content | Success, with no body. |
| 301 | Moved Permanently | The resource has a new permanent URL. |
| 302 | Found | The resource is temporarily at another URL. |
| 304 | Not Modified | Your cached copy is still current. |
| 307 | Temporary Redirect | Temporary redirect; keep the same method. |
| 308 | Permanent Redirect | Permanent redirect; keep the same method. |
| 400 | Bad Request | The request is malformed. |
| 401 | Unauthorized | No valid credentials were sent. |
| 403 | Forbidden | Access is refused. |
| 404 | Not Found | Nothing exists at this URL. |
| 405 | Method Not Allowed | This URL does not accept this method. |
| 409 | Conflict | The request clashes with the current state. |
| 410 | Gone | The resource was removed for good. |
| 422 | Unprocessable Entity | Well-formed, but fails validation. |
| 429 | Too Many Requests | Too many requests; slow down. |
| 500 | Internal Server Error | Something failed inside the server. |
| 502 | Bad Gateway | A proxy got a bad answer from upstream. |
| 503 | Service Unavailable | The server is overloaded or down. |
| 504 | Gateway Timeout | A proxy timed out waiting for upstream. |
301 vs 302 vs 307 vs 308
All four send a Location header with the new URL. They differ on two questions: is the move permanent, and may the client change the request method when it follows the redirect?
| Code | Permanent? | Method on the follow-up request |
|---|---|---|
| 301 | Yes | May change POST to GET |
| 302 | No | May change POST to GET |
| 307 | No | Must keep the original method and body |
| 308 | Yes | Must keep the original method and body |
The method rule is historical. Early browsers answered a 301 or 302 on a form POST by sending a GET to the new URL, dropping the form data, and the specification came to allow it. The 307 and 308 codes were added later to mean "repeat exactly what you sent, at this other address".
For moving website pages, 301 and 308 both tell browsers and search engines to remember the new URL. For an API endpoint that receives POST or PUT, choose 308 or 307 so the body is not lost. To make the client switch to GET on purpose, use 303 See Other.
401 vs 403
These two are confused more than any other pair, partly because the phrase for 401 says "Unauthorized" when the code is really about authentication.
- 401 means the server does not know who you are. The credentials are missing, expired or invalid. The response should carry a
WWW-Authenticateheader describing how to log in. Fixing the credentials can turn the next attempt into a success. - 403 means the server understood the request and refuses it anyway. You may be logged in as a user who lacks permission, or the resource may be closed to everyone. Logging in again will not help.
Some servers answer 404 instead of 403 so that an outsider cannot learn that a private resource exists.
How to read a raw response
When you run curl -i or open the network panel of your browser, the first lines of an HTTP/1.1 response look like this:
HTTP/1.1 301 Moved Permanently
Location: /docs/new-page.html
Content-Type: text/html; charset=utf-8
Content-Length: 162
Cache-Control: max-age=3600
Walk through it from left to right and top to bottom:
HTTP/1.1is the protocol version the server used to answer.301is the status code. The first digit, 3, says a redirect follows.Moved Permanentlyis the reason phrase. Treat it as a comment; your code should branch on the number.- The
Locationheader gives the target. A relative value like this one is resolved against the URL you requested. Cache-Controlsays how long the client may remember this answer. A mistaken 301 can stay cached in browsers after you fix the server.- A blank line ends the headers. Anything after it is the body, here a small HTML page for clients that do not follow redirects.
With 405, check the Allow header for accepted methods. With 429 or 503, check Retry-After for how long to wait. If an error response has a JSON body, the format rules in JSON syntax apply when you parse it, and a URL in a Location header follows the rules described in URL encoding.