The Complete Guide to Status Codes for Meaningful ReST APIs - The forgotten ones
Tags: rest, webdev, statuscodes, internet
Published: 2020-03-04 14:51:21

_Photo by Kristina Tripkovic on Unsplash_

In the [last article](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5) we've seen a lot of the most common HTTP Status Codes and defined a lot of stuff, like what is a status code, how do they work and why are they so important. Now let's take a look at other status codes we don't see very much but they should be used more.

> And also, we'll be continuing to use [cats](https://http.cat) and [dogs](https://httpstatusdogs.com) to illustrate our codes \o/

# Summary


<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->

<!-- code_chunk_output -->

- [Summary](#summary)
- [Codes we don't see very often, but we should](#codes-we-dont-see-very-often-but-we-should)
  - [200x](#200x)
      - [202 - Accepted](#202-accepted)
      - [204 - No Content](#204-no-content)
      - [205 - Reset Content](#205-reset-content)
      - [206 - Partial Content](#206-partial-content)
  - [300x](#300x)
      - [303 - See Other](#303-see-other)
      - [304 - Not Modified](#304-not-modified)
      - [307 - Temporary Redirect](#307-temporary-redirect)
      - [308 - Permanent Redirect](#308-permanent-redirect)
  - [400x](#400x)
      - [409 - Conflict](#409-conflict)
      - [413 - Request Entity Too Large](#413-request-entity-too-large)
      - [415 - Unsupported Media Type](#415-unsupported-media-type)
      - [422 - Unprocessable Entity](#422-unprocessable-entity)
- [Take a Break](#take-a-break)

<!-- /code_chunk_output -->


# Codes we don't see very often, but we should

Now we're going to the perfect world, where we talk about those codes which are not seen too much in the wild but they're there and should be used more often.

## 200x

### 202 - Accepted

![](https://httpstatusdogs.com/img/202.jpg)

[This is an async status code](https://tools.ietf.org/html/rfc7231#section-6.3.3), it states that the request has been accepted but it does not say anything about the actual processing state of such request, neither about the result of that which might happen on another server. The server must provide, on a header or by any other means, a pointer to a status monitor that will present the user with the status of the request sent earlier.

__When to use it:__ This is the classical ["queue"](https://docs.microsoft.com/en-us/azure/storage/queues/storage-queues-introduction?WT.mc_id=devto-blog-ludossan) situation when we have a resource that is meant to be queued for later processing. The 202 status code indicates that said resource has been accepted, so everything is fine with the request, but it cannot be processed now, but it'll be finished someday. This is often used for batch processing or some sort of CPU intensive operation, we send the request that has to be processed and, in return, we get a status monitor link. [Azure Cognitive Services](https://azure.microsoft.com/services/cognitive-services/?WT.mc_id=devto-blog-ludossan) has APIs like this.

### 204 - No Content

![](https://http.cat/204)

[This](https://tools.ietf.org/html/rfc7231#section-6.3.5) is the simplest, yet the most unused status code. It just means that everything is ok, but there's nothing to say about it...

__When to use it:__ I prefer to use it on `DELETE` requests since these kinds of requests do what they should do and nothing more. For instance, `DELETE /user/1234` should delete the user, most people return a [200 status code](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#200-ok), but this code implies that some answer would come with it, on a `DELETE` statement that's not true, we don't have anything else to say about it, the resource was just... Deleted...

### 205 - Reset Content

So... I didn't find a cat or dog image to put here and illustrate this code... BUT! The 205 code [is defined in the RFC7231](https://tools.ietf.org/html/rfc7231#section-6.3.6) and it states one of the most used things in the past – and present – __postbacks!__ Synthesizing, it says that the request was processed and the user should request a page refresh to see that change.

__When to use it:__ With [SPAs](https://docs.microsoft.com/aspnet/web-api/overview/getting-started-with-aspnet-web-api/build-a-single-page-application-spa-with-aspnet-web-api-and-angularjs?WT.mc_id=devto-blog-ludossan) this code has fallen into darkness nowadays since the last thing a [SPA](https://docs.microsoft.com/aspnet/web-api/overview/getting-started-with-aspnet-web-api/build-a-single-page-application-spa-with-aspnet-web-api-and-angularjs?WT.mc_id=devto-blog-ludossan) does is refreshing the page (after all, it's a single page application...). But, sometimes we're dealing with [202 cases](#202-accepted) and we could have a status monitor that showed us whether the process is done or not. If the resource is still processing, then it should return _202_ otherwise, _205_!

### 206 - Partial Content

![](https://http.cat/206)

This is my favorite status code, not only because we don't see it very often and it is so easy to understand, but also because it states clearly what it means and could help a lot if it was more used! [The 206 code](https://tools.ietf.org/html/rfc7233#section-4.1) states that the content that is being sent back is not the whole content the server has on that resource. This is optionally a response to a `Range` header sent by the client. [Azure Storage Services](https://docs.microsoft.com/rest/api/storageservices/specifying-the-range-header-for-file-service-operations?WT.mc_id=devto-blog-ludossan) uses this header.

__When to use it:__ I like to use it when performing `search` queries, for example, a `GET /users` query, this is obviously a list of users that I cannot return in full because it can weight a ton of bytes, so I paginate it. The first time a user requests it, the server will answer a _206_ with a custom header I like to call `X-Content-Range` which has `from-to/total`, next up we have two options:

1. The user requests `GET /users?page=2`
2. The user requests `GET /users` with a header `Range: <page number>`

Then the server will answer it with _206_ until there are no more pages, on the last page it'll answer [200](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#200-ok), if the user tries to access a page outside of the range I return a [204](#204-no-content) (if I don't want to cause panic), or a [416](#416-request-range-not-satisfiable).


## 300x

### 303 - See Other

![](https://httpstatusdogs.com/img/303.jpg)

The [See Other](https://tools.ietf.org/html/rfc7231#section-6.4.4) status code refers to the second part of a `POST` or `PUT` request when we create the resource and it is accessible through another URI, then the server should send a `Location` header stating where the new resource can be found.

__When to use it:__ You can either use the [202](#202-accepted) status code when you're talking about a document that is created but the user does not need to see it or the application does not need to take the user to the resource page. In all other situations, use 303.

### 304 - Not Modified

![](https://http.cat/304)

The "_not modified_" status code is a bit complicated due to its possibilities, however, according to the default statement of its [definition](https://tools.ietf.org/html/rfc7232#section-4.1), this status code should be returned when the client issues a request with the `If-Modified-Since` or `If-None-Match` headers and the server does not find any modified resources.

__When to use it:__ I like to use it differently, normally I return a 304 if the document altered by a `PUT` or a `PATCH` request did not suffer any modifications, this is ratter useful to define if we should reload or not the page.

> This is a personal opinion, I know this is not how the 304 code is intended to be used, but it serves me very well like this.

### 307 - Temporary Redirect

![](https://http.cat/307)

[This status code](https://tools.ietf.org/html/rfc7231#section-6.4.7) is pretty much the same as [302](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#302-found), the only difference is that the 302 allows for HTTP method switching between calls, this means I can perform a `GET` request on the first endpoint, receive a 302 and then perform a `PUT` on the specified endpoint returned by the server. With 307 this is forbidden, you must perform the request with the same method.

__When to use it:__ Same cases as [302](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#302-found), but more strict (I'd use it instead).

### 308 - Permanent Redirect

![](https://httpstatusdogs.com/img/308.jpg)

This status code is [defined on the RFC7538](https://tools.ietf.org/html/rfc7538), it's the same case as [307](#307-temporary-redirect) but instead of replacing the [302](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#302-found), it replaces the [301](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#301-moved-permanently), all other information is exactly the same.

__When to use it:__ Same cases as [301](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#301-moved-permanently), but more strict (I'd use it instead).


## 400x

### 409 - Conflict

![](https://http.cat/409)

This status code can be seen sometimes around the Web, but I wish it was more present... [The 409 code](https://tools.ietf.org/html/rfc7231#section-6.5.8) indicates a conflict in the resource state, this can be caused due to a simultaneous update or if you are trying to insert something that is already there.

__When to use it:__ I generally use it when doing `POST` requests, if the resource already exists I return a 409, for example, a user with the same email address is being registered, this is a conflict in the database.

### 413 - Request Entity Too Large

![](https://http.cat/413)

[413 status codes](https://tools.ietf.org/html/rfc7231#section-6.5.11) are the ones that tell us that we're trying to send something way bigger than expected to our server. This status code is mostly used on requests with long bodies or very heavy requests. [Azure Storage Services](https://azure.microsoft.com/free/storage/?WT.mc_id=devto-blog-ludossan) also uses these responses when creating or editing new blobs.

__When to use it:__ Mostly used when the request has a body, on `POST`, `PUT` and `PATCH` methods. The most common use case is image upload if the image is bigger than the server is willing to process.

### 415 - Unsupported Media Type

![](https://http.cat/415)

This one is pretty straight forward too. [Unsupported Media Type](https://tools.ietf.org/html/rfc7231#section-6.5.13) is used when the server does not support the `Content-Type` of the incoming request. Once again, storage APIs like [Azure](https://azure.microsoft.com/free/storage/?WT.mc_id=devto-blog-ludossan) end up using it a lot when creating blobs

__When to use it:__ Again, the image upload case, let's imagine we have a document being uploaded as PDF, but we only accept JPEG, this would return 415.

> This is also a great representation of why we should not use [400](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#400-bad-request) code for _everything_

### 422 - Unprocessable Entity

![](https://httpstatusdogs.com/img/422.jpg)

This status code [is defined on the RFC4918](https://tools.ietf.org/html/rfc4918#section-11.2), and it is the main reason why I wrote this article. Most people use [400](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#400-bad-request) status code when the payload of a request is wrong, which means that is a bad request, but the problem is not in the request itself, it is in the payload, hence why [400](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#400-bad-request) should not be used on these cases, instead, we should use 422 to say that the request is good, the server can understand it, but cannot process it due to a wrong sent entity.

__When to use it:__ Validation errors, period. If your payload does not match a validation pattern, let's say, the `email` field is not a valid email, then this entity is not processable, thus 422.

# Take a Break

Now we've reached the end of section two! In the last article, we'll be explaining other status codes that are either unused or have just ended up forgotten in the swamps of the Internet!

See ya!