HTTP status codes

Every HTTP status code, explained in plain English. Type a code like 502, a class like 4xx, or words like “rate limit” to find it, then open a code for its causes, fixes and an example response.

79 status codes/ search Enter open the first match

The five classes

The first digit of a status code tells you what kind of answer it is. A client that meets a code it doesn’t know treats it like the x00 code of its class, so an unknown 4xx is handled like a 400.

  • 1xx Informational. An interim answer: “carry on” (100), “switching to WebSocket” (101) or “start loading these files” (103). A final response always follows.
  • 2xx Success. It worked. 200 is the everyday one, with 201 for something created and 204 when there’s nothing to send back.
  • 3xx Redirection. Look elsewhere (the Location header says where), or use your cached copy (304).
  • 4xx Client error. Something about the request is wrong: the address, the login, the data or how often you’re asking. Sending the same request again won’t help, apart from timing problems like 429.
  • 5xx Server error. The request may have been fine, but the server or something behind it failed. Trying again later often works.

The codes you’ll see most

CodeNameIn short
200OKThe request worked and the response contains the result.
201CreatedThe request worked and created something new, usually found at the URL in the Location header.
204No ContentThe request worked and there is nothing to send back.
301Moved PermanentlyThe page has moved for good to the URL in the Location header.
302FoundThe page is temporarily at the URL in the Location header.
304Not ModifiedYour cached copy is still up to date, so use that.
400Bad RequestThe server can’t or won’t handle the request because something in it is malformed.
401UnauthorizedYou need to log in, or the credentials you sent are missing, wrong or expired.
403ForbiddenThe server understood who you are and won’t let you do this.
404Not FoundThere’s nothing at this URL, or the server won’t say whether there is.
409ConflictThe request clashes with the current state of the resource, such as an edit conflict or a duplicate.
422Unprocessable ContentThe request is well formed, but the data in it doesn’t make sense, such as failing validation.
429Too Many RequestsYou’ve sent too many requests in a given time. Slow down and try again later.
500Internal Server ErrorSomething went wrong on the server, and it has no more specific code to describe it.
502Bad GatewayA proxy or load balancer got an invalid response, or none at all, from the server behind it.
503Service UnavailableThe server can’t handle the request right now, usually because it’s overloaded or down for maintenance.
504Gateway TimeoutA proxy or load balancer gave up waiting for the server behind it to reply.

401 or 403?

The names are confusing. 401 Unauthorized really means unauthenticated: the server doesn’t know who you are, because the token or password is missing, wrong or expired. It has to send a WWW-Authenticate header saying how to log in. 403 Forbidden means the server knows who you are, or doesn’t care, and the answer is still no. If logging in again could fix it, use 401. If it couldn’t, use 403. If you’d rather not admit the thing exists at all, 404 is allowed too.

301, 302, 307 or 308?

Two questions decide it: is the move permanent, and must the method be kept?

May change POST to GETKeeps method and body
Permanent301 Moved Permanently308 Permanent Redirect
Temporary302 Found307 Temporary Redirect

For ordinary page visits they behave the same, so the choice is really permanent (search engines move to the new URL, browsers cache it) or temporary. After a form submission, use 303 See Other, which always switches to GET so a refresh doesn’t send the form twice.

502, 503 or 504?

All three usually come from a proxy, load balancer or CDN in front of the real application.

  • 502 Bad Gateway: the app answered badly or not at all. It crashed, isn’t running, or refused the connection.
  • 503 Service Unavailable: the service says it can’t take requests right now, because of maintenance or overload. A Retry-After header can say when to come back.
  • 504 Gateway Timeout: the app is running but didn’t reply before the proxy gave up waiting.

Behind Cloudflare, you’ll see its own versions with more detail: 521 (connection refused), 522 (couldn’t connect in time) and 524 (connected, but no response in time).

Picking the right code for an API

  • Be specific where it helps the client act: 201 with a Location after creating, 204 when there’s no body, 202 when work is queued.
  • Never send 200 with an error inside. Caches, monitoring, browsers and retry logic all trust the status code.
  • Use 4xx for anything the caller can fix, and 5xx only when your side failed. Your alerts will thank you.
  • Put the detail in the body, ideally in the standard “problem details” format (application/problem+json, RFC 9457), with a message a person can read.
  • Use 429 with Retry-After for rate limits, so well-behaved clients slow down by themselves.

Debugging an API call? The JWT decoder explains most 401s, the JSON formatter finds the broken JSON behind many 400s, and the URL decoder takes apart long URLs.

The definitions come from RFC 9110, section 15, the RFCs that added later codes, and the IANA status code registry. Unofficial codes link to the documentation of the software that uses them.

Questions people ask

How many HTTP status codes are there?
The IANA registry lists around 60 codes that are in use, from 100 to 511. This page also includes 16 unofficial codes you’ll meet in practice, from nginx, Cloudflare and frameworks such as Laravel, clearly marked as unofficial.
What’s the difference between 401 and 403?
401 means the server doesn’t know who you are: log in or send valid credentials. 403 means it knows (or doesn’t need to know) and still won’t allow the request. Logging in again fixes a 401 but not a 403.
Which status code should an API use for validation errors?
Most APIs use 400 or 422. 400 suits requests the server can’t parse, and 422 suits well-formed requests with invalid data. Either is fine if you’re consistent and explain the problem in the response body.
Are codes like 499 and 522 real HTTP status codes?
Not officially. 499 is nginx’s way of logging that a client gave up, and 520 to 530 are Cloudflare’s codes for problems reaching a website’s own server. They aren’t in any RFC, but they’re common enough to need explaining.
Can I make up my own status codes?
You can, but clients only understand the first digit of a code they don’t recognise: an unknown 4xx is treated like 400 and an unknown 5xx like 500. It’s almost always better to use a standard code and put the detail in the response body.
↑↓ move↵ openesc close