The Complete Guide to Status Codes for Meaningful ReST APIs - Conclusion
Tags: http, rest, internet, webdev
Published: 2020-03-06 04:01:41

_Photo by Ilya Pavlov on Unsplash_

We talked about [common status codes](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5) and [not-so-common ones](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-the-forgotten-ones-c9a), but the list does not end there! We still need to talk about those other codes that are even less used, but they're so specific we might never see them!

# Summary

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

<!-- code_chunk_output -->

- [Summary](#summary)
- [Other Status Codes](#other-status-codes)
  - [100x](#100x)
      - [100 - Continue](#100-continue)
      - [101 - Switching Protocols](#101-switching-protocols)
  - [200x](#200x)
      - [203 - Non-Authoritative Information](#203-non-authoritative-information)
  - [300x](#300x)
      - [300 - Multiple Choices](#300-multiple-choices)
  - [400x](#400x)
      - [406 - Not Acceptable](#406-not-acceptable)
      - [407 - Proxy Authentication Required](#407-proxy-authentication-required)
      - [408 - Request Timeout](#408-request-timeout)
      - [410 - Gone](#410-gone)
      - [411 - Length Required](#411-length-required)
      - [412 - Precondition Failed](#412-precondition-failed)
      - [414 - Request-URI Too Long](#414-request-uri-too-long)
      - [416 - Request Range Not Satisfiable](#416-request-range-not-satisfiable)
      - [417 - Expectation Failed](#417-expectation-failed)
      - [418 - I'm a Teapot](#418-im-a-teapot)
      - [426 - Upgrade Required](#426-upgrade-required)
      - [428 - Precondition Required](#428-precondition-required)
      - [431 - Request Header Fields Too Large](#431-request-header-fields-too-large)
      - [451 - Unavailable For Legal Reasons](#451-unavailable-for-legal-reasons)
      - [499 - Client Closed Request](#499-client-closed-request)
  - [500x](#500x)
      - [501 - Not Implemented](#501-not-implemented)
      - [505 - HTTP Version Not Supported](#505-http-version-not-supported)
      - [511 - Network Authentication Required](#511-network-authentication-required)

<!-- /code_chunk_output -->

# Other Status Codes

Now we've reached the point where we still have status codes to talk about but they're not so used or so meaningful to most applications, but that doesn't mean we should not use them on our APIs if needed!

It's important to say that because most people just stick to the most common ones, there's a whole new world of status codes that should be leveraged when creating APIs.

## 100x

## 100 - Continue

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

This is one very common code, but not so used by a lot of people because it is generally not sent by the client itself. Actually, the client expects a [100 status code](https://tools.ietf.org/html/rfc7231#section-6.2.1) to continue sending requests.

__When to use it:__ This code is used as server response when clients send partial requests containing the `Expect: 100-continue` header. This header indicates that the request that has been sent only contains the headers for validation and, after the request headers are validated, the server should return a 100 status code to indicate that the client can now send the request body (in cases where there is a body). If the client receives a [417](#417-expectation-failed) status code, this indicates that the server cannot handle the `Expect` header.

### 101 - Switching Protocols

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

[This](https://tools.ietf.org/html/rfc7231#section-6.2.2) is an acknowledgment from the server indicating that it has agreed to the client's request of switching protocols on an [`Upgrade` header](https://tools.ietf.org/html/rfc7230#section-6.7). The server __must__ answer with another `Upgrade` header indicating to which version of the protocol it will switch into.

__When to use it:__ Server side only, not much use for clients.


## 200x

### 203 - Non-Authoritative Information

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

[The 203 code](https://tools.ietf.org/html/rfc7231#section-6.3.4) is an authorized man-in-the-middle, it says that the upstream server behind a [proxy server](https://docs.microsoft.com/azure/service-fabric/service-fabric-reverseproxy-setup?WT.mc_id=devto-blog-ludossan) returned [200](#200-ok), but the proxy server changed the payload.

__When to use it:__ When using [proxy servers](https://docs.microsoft.com/azure/service-fabric/service-fabric-reverseproxy-setup?WT.mc_id=devto-blog-ludossan), this is often responded when requests get injected with more information by the proxy when responding to a request.

## 300x

### 300 - Multiple Choices

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

The [multiple choices](https://tools.ietf.org/html/rfc7231#section-6.4.1) status code indicates that the target resource can be found in more than one URI or it has more than one representation. If the request is a `HEAD` method, then the server _should_ return a `Location` header indicating the location of the preferred resource. In the cases of methods other than `HEAD`, the server should send a payload along with the 300 code containing a list of all representations of this resource so the client can choose which one is most appropriate.

__When to use it:__ This is generally used on media servers, where you can have multiple locations for the same file, like a [CDN](https://azure.microsoft.com/services/cdn/?WT.mc_id=devto-blog-ludossan), when you ask for a file, the [API gateway](https://azure.microsoft.com/services/api-management/?WT.mc_id=devto-blog-ludossan) server can respond to a 300 status and asks you to choose from a list of available locations. Let's try by example on a website requesting an image from a [CDN](https://azure.microsoft.com/services/cdn/?WT.mc_id=devto-blog-ludossan), the client sends a `GET` request for the image, which is responded with 300 and a list of available resources divided into regions, the client can then choose the closest region and get the image.


## 400x

### 406 - Not Acceptable

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

[406 status codes](https://tools.ietf.org/html/rfc7231#section-6.5.6) are pretty simple. They state that the resource requested in the format of the `Accept` header by the client is not available in that format.

__When to use it:__ Pretty common when using [ReST](https://docs.microsoft.com/azure/architecture/best-practices/api-design?WT.mc_id=devto-blog-ludossan), let's suppose we have an API that returns animal names, we can get that information both in XML and JSON, so the client must specify a `Accept: application/xml` or `Accept: application/json` header in the request, if our client specifies `Accept: image/jpeg` then we return 406.

### 407 - Proxy Authentication Required

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

This status code [is defined in the RFC7235](https://tools.ietf.org/html/rfc7235#section-3.2), in short, what it says is that a proxy between the server and the client requires the latter to authenticate before continuing.

__When to use it:__ Classic infrastructure problem, I don't know about you but every time I go to a company wifi there's a proxy that returns me 407 so I can authenticate to use the Internet.

### 408 - Request Timeout

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

[By the 408 code](https://tools.ietf.org/html/rfc7231#section-6.5.7) the server decides to close an opened connection due to the amount of time the client took to send the complete request over to it. All servers are prepared to receive and process a request in a given timeframe and, if the client fails to submit the whole request within this timeframe, the server closes the connection.

__When to use it:__ Generally this happens automatically when our webserver detects a single connection has been opened for too long, usually happening when we upload large files that take a while more than the server is willing to wait.

### 410 - Gone

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

[Gone](https://tools.ietf.org/html/rfc7231#section-6.5.9) is one of the most powerful HTTP Status Codes since it explicitly says that the resource is not only not available, but it won't be ever available again. This is more powerful than [404](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#404-not-found) because it tells search engines to remove that resource from their indexes.

__When to use it:__ This is mostly used when we delete a resource, for instance, most of the times I use a logical delete to keep the data in the database but a `deletedAt` column keeps me from showing them in the page and, if someone tries to access this record, I can return a 410.

### 411 - Length Required

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

The [411 code](https://tools.ietf.org/html/rfc7231#section-6.5.10) is simple, the client forgot to send the header `Content-Length`.

__When to use it:__ Mostly unused in everyday app situations, but can be used if you're doing file upload and wants to know the complete file size beforehand so you can validate if the file is valid or not.

### 412 - Precondition Failed

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

[Specified in RFC7232](https://tools.ietf.org/html/rfc7232#section-4.2), the 412 status code is only returned if the server supports the `If-Unmodified-Since` or `If-None-Match` and the client sends a request that cannot satisfy that condition.

__When to use it:__ There are not many places to go from here, basically we just attain to the definition.

### 414 - Request-URI Too Long

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

[This status code](https://tools.ietf.org/html/rfc7231#section-6.5.12) hasn't appeared in a while since most servers nowadays can process a huge amount of data. But the 414 status code says that the requested URI was too long for the server to process.

__When to use it:__ Pretty straight forward also, nothing we can do more than that.

### 416 - Request Range Not Satisfiable

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

This code [is defined in RFC7233](https://tools.ietf.org/html/rfc7233#section-4.4) and states that when a client sends a `Range` header outside of the available range the server can process, this should be the answer.

__When to use it:__ As we saw [in the last article](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-the-forgotten-ones-c9a#206-partial-content), 416 status codes can be returned if you are paginating a request and the user requests a page outside of the maximum page range.

### 417 - Expectation Failed

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

[This status code](https://tools.ietf.org/html/rfc7231#section-6.5.14) is more like a continuation from the [406](#406-not-acceptable) one but not with media types since it states that the `Expect` header sent by the client cannot be satisfied by the server.

__When to use it:__ A common case is when our server does not support the [100](#100-continue) header, if that is the case and the client sends `Expect: 100-continue`, then we return 417.

### 418 - I'm a Teapot

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

This one is not even defined in the RFC because it is not an official status code. The 418 is part of [an April's fool joke](https://en.wikipedia.org/wiki/Hyper_Text_Coffee_Pot_Control_Protocol) that created a new protocol called _Hyper Text Coffee Pot Control Protocol_,

__When to use it:__ Pure fun, only (unless you're a teapot)

### 426 - Upgrade Required

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

[This code](https://tools.ietf.org/html/rfc7231#section-6.5.15) states that the client should upgrade its TLS version to the version specified in the `Upgrade` header.

__When to use it:__ Generally used when servers have specific and strict rules for security protocols, in these cases, when a protocol is not accepted it'll send back a 426.

### 428 - Precondition Required

Another status code that comes around without any dog or cat to illustrate it (sad)... But! The 428 status code [is defined in the RFC6585](https://tools.ietf.org/html/rfc6585#section-3), which is the document for additional HTTP status codes. This is the server telling the client that it requires the `If-Match` header.

__When to use it:__ Not much to say, the best approach is to stick to the definition.

### 431 - Request Header Fields Too Large

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

The 431 status code is [also defined in the RFC6585](https://tools.ietf.org/html/rfc6585#section-5) and the message says it all. This happens when one of the headers or the whole set of headers is larger than the maximum limit imposed by the server.

__When to use it:__ Again, the definition is pretty straight forward here, this is a request problem with headers, being so specific makes this status code less usable in other cases.

### 451 - Unavailable For Legal Reasons

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

This status code is special because [it has a whole RFC to itself](https://tools.ietf.org/html/rfc7725). Again, both the message and the code are very clear, the resource is not available due to some legal reason.

__When to use it:__ This is more common in download websites or digital products, where a resource can be traced back to a property belonging to someone, this property can become unavailable for a legal reason, let's say a book illegally uploaded to a website, if you try to download it, you get 451.

### 499 - Client Closed Request

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

This is also special because it is not a standard status code introduced by IETF or W3C, but rather by NGINX. This status code is __VERY__ specific to NGINX cases when the client closes the connection whilst the server is still processing it.

__When to use it:__ NGINX-bound so I would not use it anywhere else.


## 500x

### 501 - Not Implemented

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

Back to the [original definitions](https://tools.ietf.org/html/rfc7231#section-6.6.2) entering the realm of the "I messed things up", we got the 501 status code, which is destined to inform the client that the request method hasn't been understood by the server or the server knows it but cannot fulfill it.

__When to use it:__ I use it mostly when I have a method that is due to be implemented in the future (so it is not a [405](https://dev.to/khaosdoctor/the-complete-guide-to-status-codes-for-meaningful-rest-apis-1-5c5#405-method-not-allowed)) however, it is not implemented yet, which means it is an ongoing work. I know you'll all judge me about it, but some times devs need to put things online fast for the sake of the business, so we do not have time to finish a few features here and there, that's when 501 gets used.

> Despite 501 being more server-related, you can also use it as an app implementation issue since the client does not recognize the server and the API as separate subjects.

### 505 - HTTP Version Not Supported

Another pictureless status code :(, but a very important one! This status code is defined [in the last section of RFC7231](https://tools.ietf.org/html/rfc7231#section-6.6.6) as being a way to tell clients to upgrade their protocol. By definition, this is only used to tell when the server does not support the __major__ HTTP version, and then the server _SHOULD_ send a representation of a message telling why the version is not supported and what other protocol versions it allows.

__When to use it:__ When you do not accept HTTP/1.1 or HTTP/1.0 requests, only HTTP/2 ones.

### 511 - Network Authentication Required

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

We talked about [407](#407-proxy-authentication-required) being the one to tell the client that it needs to authenticate to continue, right? Now, the [511 code](https://tools.ietf.org/html/rfc6585#section-6) also says that, but at the network level. Then the server should send a link to a resource that allows the user to submit credentials.

__When to use it:__ Developers will rarely use it since it's a network-related status code, but, if you can verify whether your user is connected to the network or not, then this is how you use it.

# Conclusion

Thanks a lot for reading this series! I hope you liked it and, if you found any typos or mistakes, please let me know :D 

You can reach me out anytime on [@_staticvoid on Twitter](https://twitter.com/_staticvoid) or at [lsantos.dev](https://lsantos.dev)!

See ya in the next articles!