The Complete Guide to Status Codes for Meaningful ReST APIs - Conclusion

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!

Summary

• Summary
• Other Status Codes
  • 100x
    • 100 - Continue
    • 101 - Switching Protocols
  • 200x
    • 203 - Non-Authoritative Information
  • 300x
    • 300 - Multiple Choices
  • 400x
    • 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
  • 500x
    • 501 - Not Implemented
    • 505 - HTTP Version Not Supported
    • 511 - Network Authentication Required

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

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 Expect header.

101 - Switching Protocols

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.

200x

203 - Non-Authoritative Information

The 203 code is an authorized man-in-the-middle, it says that the upstream server behind a proxy server returned 200, but the proxy server changed the payload.

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.

300x

300 - Multiple Choices

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.

400x

406 - Not Acceptable

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.

407 - Proxy Authentication Required

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.

408 - Request Timeout

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.

410 - Gone

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.

411 - Length Required

The 411 code 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

Specified in RFC7232, 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

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.

416 - Request Range Not Satisfiable

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.

417 - Expectation Failed

This status code is more like a continuation from the 406 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 header, if that is the case and the client sends Expect: 100-continue, then we return 417.

418 - I'm a Teapot

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)

426 - Upgrade Required

This code 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, 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

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.

451 - Unavailable For Legal Reasons

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.

499 - Client Closed Request

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

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.

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 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

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.

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 or at lsantos.dev!

See ya in the next articles!

Comments

[Michael Freidgeim]

Our API communicates with BrainTree payment provider, that may return “payment declined”. Should we use 402 (Payment Required) or you can suggest other code?

[Lucas Santos]

In this case I suggest you use other code, the 402 relates to a resource that itself needs a payment, like when you have a premium API and this API is not paid for by the user (just an example).

One code you can use, if your product communicates with something external and you expect something to be true (the payment), you can extend the definition to business rules and use either 412 as this is a precondition for the API to go forth, or 417 (my personal favorite) as it's part of an expectation your server had but it didn't come true.

If you really want to attain to the definition, you can add the Expect header too.