lukeprosserBlogProjects

HTTP Status Codes Explained

There are a lot of HTTP status codes. A LOT. However, the good news is that you don’t need to remember them all, as certain HTTP status codes are much more common (and more useful) than others.

In this lesson we’ll go over the most essential codes that you need to know in order to get up and running building and interacting with web APIs.

We will cover:

For more information on the HTTP protocol, check out What Is HTTP?.

TLDR

Not all HTTP status codes are of equal importance. Here are the ‘top 10’ HTTP status codes you need to know:

  • 200 OK
  • 201 Created
  • 204 No Content
  • 304 Not Modified
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 500 Internal Server Error

Why status codes?

The whole purpose of HTTP status codes is to provide the client with the most useful information possible from the server, without having to write custom responses every time.

Each predefined status code has its own meaning, and we can use this meaning to respond appropriately on the client side.

100-level codes

The Information 1xx category of codes can pretty much be ignored entirely.

You’re extremely unlikely to ever come across these or have a need to use them when building APIs.

200-level codes

You’ll see this category of codes all the time.

Any code in the 200 category means that the request was successful and completed correctly.

200 OK

The 200 code simply means ‘ok’, nothing further to add, just that the request was successful. It’s the most general success message you can send.

201 Created

If you’re building a REST API, all of your POST requests should return a 201 status code which means ‘created successfully’.

You could technically return a 200 status code after a successful creation, but sending a 201 gives the browser a little more information, which could also be useful when handling the response in a UI.

204 No Content

This code essentially means that the request went well but there’s nothing to return. The most common example of this type of request is a delete request, where the requested resource was deleted but there’s nothing else to return.

The deleted resource no longer exists, so we wouldn’t return that, we just want to let the client know that the deletion was a success.

300-level codes

300 codes handle all things related to redirection. If a user visits one URL, and that URL redirects them to another URL, the user’s browser will receive a 300-level status code from the first URL.

This is effectively saying: “this web page used to be located here, but it’s been moved to here”.

304 Not Modified

Ironically the 304 status code doesn’t refer to the redirection from one URL to another. Instead it deals with caching.

When an application makes a call to an API, it may not need to receive all the data for every single request. The data may not change very often, but the app may need to query the endpoint frequently just to check if any changes have occurred.

When the application makes the call to the API, it can check if the data has changed since a specified time. If the data has not changed since that time, the server can send back the 304 status code to indicate that the data has not been modified.

This is more efficient because the server doesn’t need to send any additional information and the client doesn’t need to download any extra information.

If the data has changed since the specified time, the server can send a 200-level code along with the requested data.

400-level codes

400-level codes relate to errors i.e. something has gone wrong. A 400-level error is essentially an error from the client side.

For example, the user interacting with the API provided incorrect information or they aren’t authorised.

400 Bad Request

This is a general error indicating that something went wrong and that the provided user information was bad in some way.

Generally you would use a 400 code if you don’t know the specific reason for the user information being bad or if the user sent you invalid parameters.

For example, the API might expect an email address and a username, but the client only sent a username.

401 Unauthorized

The unauthorized error essentially means that a user is trying to access data that requires some form of authentication (e.g. a login, API key etc.), and that the correct authentication either was not passed or was not correct.

401 is essentially saying “I don’t know who you are”.

403 Forbidden

A 403 code deals with levels of access. In this scenario, a user has sent the correct credentials (e.g. an API key) but they don’t have the relevant permissions required to access certain data.

For example, an application may have various access levels, such as a basic user level and an admin user level.

403 is saying “I know who you are, but you can’t access the data you've requested”.

404 Not Found

The 404 status code is perhaps the most commonly known. This means that the content the user is trying to access doesn’t actually exist.

For example, an application makes a request to an API endpoint that doesn’t exist, or a user tries to navigate to a page that doesn’t exist.

500-level codes

In contrast to 400-level codes that relate to a user error, 500-level codes refer to something incorrect happening on the server.

For example, the database could be down or an exception error is thrown.

500 Internal Server Error

This error code is by far the most common on the server side. This usually occurs when there is a problem with the server that we didn’t expect.

For example there may be a bug in the code that throws an error, or the database might be down.

We can’t specifically handle these unexpected scenarios, so we generally throw a 500 error.

A 500 error is useful because it communicates to the client or application that what they are sending isn’t wrong. Rather, there is something wrong on the server side and hopefully it should be resolved.

Conclusion

There we have it! The most essential HTTP status codes that you need to know in order to build and interact with web APIs.

For more information on the HTTP protocol and how it works, check out What Is HTTP?.