HTTP status codes to know

Published on
Table of Contents

It is always easy to Google status codes, and there are not too many of them. But here are the ones I think most developers who use HTTP requests should probably know by heart (or be very familiar with).

It also explains when and why I think they should be used.

if I am honest: I often Google them to double check I have the right one especially for 301/302 redirects...

Success statuses (2xx)

Status code 200 - ok

This is your standard response for most GET requests.

Status code 201 - created

Used when created content, like after a form submission that saves a document.

This should be your standard response when a POST request was completed and something (a new row/record) was created. I also see it used with PUT/PATCH when content was updated (I'd argue that goes against the name of created)

You can return it with an empty body but it is common to include some kind of message.

Status code 204 - no content

Indicates the request went through ok, but no content to return. I don't see this in use often. Sometimes used in POST/PATCH/PUT requests to indicate it went ok.

Redirect statuses (3xx)

Status code 301 - permanent redirect

Use this if /incoming-request should always redirect to /some-new-location

I would not recommend using this unless its for strategic SEO purposes or if you know 100% it will always redirect there.

Once cached, it can be hard to bust this cached redirect and your browser will tend to always skip making a HTTP request (to the old /incoming-request url) and it will automatically request the redirected location.

This can cause headaches when its decided to point to a new location.

Status code 302 - temporary redirect

Similar to a 301... except browsers will continue to re-request it. This is useful if a redirect might change.

For internal apps or anything not affected by SEO I'd often recommend using a 302 if possible.

User Error codes (4xx)

Status code 400 bad request

Use this when the user requested something incorrect (like incorrect/missing params

Status code 401 not authorized (not logged in/invalid credentials)

Use this when not logged in. This indicates to the user they need to (re)login

Status code 403 forbidden (logged in, but don't have right permissions)

Use when user is logged in, but user has wrong permissions/privileges. In other words, authenticated, but not authorised to request that content

Status code 404 not found

Content for the URL was not found. e.g. you request and it will return 404.

Status code 422 unprocessable entity (often used for validation errors)

If the submitted data is incorrect, like when failing validation.

Server errors (5xx)

Status code 500 error - internal server error

Something went wrong in your backend code, this is probably the common and generic error message.

Status code 501 - not implemented

Not too common in my experience (it would normally be a 4xx error to tell the user to not request whatever they couldn't handle), but this can be used when the server is unable to support something that was requested.

Status code 502 - bad gateway (proxy/gateway error)

Used when proxy/load balancer/gateway receives an invalid response from the server it passed the request to

Status code 503 service unavailable (too much load)

503s are often when the server is under too much load. Load balancers will return this. It is often temporary

Status code 504 gateway timeout (proxy/load balancer/gateway returns this when the server takes too long)

Often returned by a load balancer, if the server it forwarded the request to has timed out (e.g. after 30 secs).