Photo by Ilya Pavlov on Unsplash
We talked about common status codes and not-so-common ones, 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!
Other Status Codes
- 406 - Not Acceptable
- 407 - Proxy Authentication Required
- 408 - Request Timeout
- 410 - Gone
- 411 - Length Required
- 412 - Precondition Failed
- 414 - Request-URI Too Long
- 416 - Request Range Not Satisfiable
- 417 - Expectation Failed
- 418 - I'm a Teapot
- 426 - Upgrade Required
- 428 - Precondition Required
- 431 - Request Header Fields Too Large
- 451 - Unavailable For Legal Reasons
- 499 - Client Closed Request
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.
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 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 status code, this indicates that the server cannot handle the
This is an acknowledgment from the server indicating that it has agreed to the client's request of switching protocols on an
Upgrade header. 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.
When to use it: When using proxy servers, this is often responded when requests get injected with more information by the proxy when responding to a request.
The multiple choices 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, when you ask for a file, the API gateway 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, 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.
406 status codes 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, 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.
This status code is defined in the RFC7235, 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.
By the 408 code 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.
Gone 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 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.
The 411 code is simple, the client forgot to send the header
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.
Specified in RFC7232, the 412 status code is only returned if the server supports the
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.
This status code 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.
This code is defined in RFC7233 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, 416 status codes can be returned if you are paginating a request and the user requests a page outside of the maximum page range.
When to use it: A common case is when our server does not support the 100 header, if that is the case and the client sends
Expect: 100-continue, then we return 417.
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 that created a new protocol called Hyper Text Coffee Pot Control Protocol,
When to use it: Pure fun, only (unless you're a teapot)
This code states that the client should upgrade its TLS version to the version specified in the
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.
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, which is the document for additional HTTP status codes. This is the server telling the client that it requires the
When to use it: Not much to say, the best approach is to stick to the definition.
The 431 status code is also defined in the RFC6585 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.
This status code is special because it has a whole RFC to itself. 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.
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.
Back to the original definitions 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) 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.
Another pictureless status code :(, but a very important one! This status code is defined in the last section of RFC7231 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.
We talked about 407 being the one to tell the client that it needs to authenticate to continue, right? Now, the 511 code 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.
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
See ya in the next articles!