How to select the correct HTTP status code

This article is from my translation of the Infoq Chinese station, the original address is: Http://www.infoq.com/cn/news/2015/12/how-to-choose-http-status-code

As we all know, each HTTP response will have a status code, but for many developers, usually use the most of the number of status code is 200, 400, 404, 500 and so on. That many other status codes the application in what scenario, when should use which state code to become a worthy of our deep thinking of the problem. Even in a company like Facebook, the smart developers will probably only return 200 of the APIs they build. To do this, Michael Kropat specifically analyzes the application scenarios for each status code, and why we need to differentiate between different status codes in such a meticulous manner, while also talking about the benefits of doing so.

Is there anything more simple than returning an HTTP status code? Does the page render? If rendered, then return 200 chant. Page does not exist? That's 404. Need to redirect users to another page? Then use 302, maybe 301.

It's all so simple, but when someone tells you that you're not doing things in a restful way, you're probably going to be vigilant. Does the new resource return RFC-compatible, roy-fielding-recommended status codes? Is it only 200? Maybe it's 204 No Content, 202 Accepted, or 201 Created?

The problem is that the official http/1.1 Guide (RFC) was originally released in 1997. At that time we were still using Netscape Navigator, 33.6kbps of the debug demodulator to surf the internet. This is like using the art of war in modern business strategies. These valuable suggestions do not change over time. However, we need to really understand them.

If you have a visual decision tree, it can help you quickly identify status codes that match your situation, so you can ignore irrelevant ones. Please look.

It seems obvious, but I find that a lot of people fall into it and ask, "Should this be the case with 503 Service unavailable or 404 Not Found?" Stop. If you think of a specific status code in a completely different response category, it means that your approach is completely wrong. Take a look at the picture above.

Before I proceed, I propose a few points:

• You don't have to listen to me. See RFC 7231 and httpstatuses.com directly
• The readers I'm looking for are developers who create websites or use rest APIs.
• I have roughly divided the response code into 3 broad categories

One last point: I'm not really qualified to express my opinion on this topic, I've just read some RFCs and developed some APIs. If you feel that I am wrong, or do not use the status code you prefer to use, then in the comments at the end of the text, we will discuss together.

2xx/3xx

4XX

5XX

Why is it important to say that the status code

While many of the smart developers on Facebook only return 200 when building APIs, what I want to say is that the status code is really important. Existing status codes are a bit too broad for modern web/api. If the response is to include some details in the application-specific format, such as which field validation failed, what is the reason for the client to handle the response in a more meaningful way. So why not spend more time studying the "less common" HTTP status codes?

When it comes to why using specific status codes is very important, one of the reasons people love to mention is that HTTP is a layered system, there may be proxies, caches, or other HTTP libraries between the client and server, and if the response code makes sense, it will work better. However, I think this explanation is untenable, for example, in the future we all use HTTPS, we also disable all proxy and cache nodes, you can say that this time the status code is useless?

Here, I want to talk about 3 reasons why I think the status code is still important:

1. The client can take different actions for different status codes (or it can be easily extended to respond):

• 301 Moved Permanently and 302 found have SEO metaphors for Google and other search engines
• 301 Moved Permanently has the meaning of caching, while 429 Too many requests does not have the meaning of caching, and so forth
• The client library can process 429 Too many by retrying the request after a period of delay requests
• The client library can take a similar approach to 503 Service unavilable

2. Many status codes represent situations that can be handled by a special response.

• Returns 404 instead of 405 Method not allowed APIs sometimes make me mad, "Did I lose the wrong URL or use the wrong HTTP method?"
• The correct distinction between 502 bad Gateway and the Internal Server error will save you a lot of debugging time.

3. Believe it or not, a number of popular APIs have been established, for example, to return to 201 Created, 429 Too Many requests, or 503 Service unavilable. If you follow these conventions, it's easier for users to use your site/api and easier to solve when they're having problems.

If you are having problems using HTTP status codes, you can also refer to the following resources:

• HTTP Status Code Reference
• HTTP status codes used by world-famous APIs
• HTTP status codes visualized as a subway map
• Status Codes to Cat Memes as a Service
• Status Codes to Dog Memes as a Service

Readers, I believe many of you have been or are designing the API, so what do you think about the status code in this process? What are the insights? Welcome to share it with other Infoq readers.

How to select the correct HTTP status code