HTTP Status Codes

The three-digit number at the top of every HTTP response, what each class means, and how to tell the commonly confused codes apart.

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.

CodeReason phrasePlain meaning
200OKThe request worked; the body holds the result.
201CreatedA new resource was created.
204No ContentSuccess, with no body.
301Moved PermanentlyThe resource has a new permanent URL.
302FoundThe resource is temporarily at another URL.
304Not ModifiedYour cached copy is still current.
307Temporary RedirectTemporary redirect; keep the same method.
308Permanent RedirectPermanent redirect; keep the same method.
400Bad RequestThe request is malformed.
401UnauthorizedNo valid credentials were sent.
403ForbiddenAccess is refused.
404Not FoundNothing exists at this URL.
405Method Not AllowedThis URL does not accept this method.
409ConflictThe request clashes with the current state.
410GoneThe resource was removed for good.
422Unprocessable EntityWell-formed, but fails validation.
429Too Many RequestsToo many requests; slow down.
500Internal Server ErrorSomething failed inside the server.
502Bad GatewayA proxy got a bad answer from upstream.
503Service UnavailableThe server is overloaded or down.
504Gateway TimeoutA 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?

CodePermanent?Method on the follow-up request
301YesMay change POST to GET
302NoMay change POST to GET
307NoMust keep the original method and body
308YesMust 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-Authenticate header 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:

  1. HTTP/1.1 is the protocol version the server used to answer.
  2. 301 is the status code. The first digit, 3, says a redirect follows.
  3. Moved Permanently is the reason phrase. Treat it as a comment; your code should branch on the number.
  4. The Location header gives the target. A relative value like this one is resolved against the URL you requested.
  5. Cache-Control says how long the client may remember this answer. A mistaken 301 can stay cached in browsers after you fix the server.
  6. 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.