I’m currently implementing an HTTP API, my first ever.
I’ve been spending a lot of time looking at the Wikipedia page for HTTP status codes, because I’m determined to implement the right codes for the right situations. Listed on that page is a code with number 420, which is a custom code that Twitter used to use for rate limiting.
There is already a code for rate limiting, though. It’s 429.
This led me to wonder why they would set a custom one, when there is already a use case. Is that just being cute? And if so, then which circumstances would make it acceptable to return a different status code, and what, if any problems may clients have with it?
I read somewhere that Mozilla doesn’t implement the joke 418: I’m a teapot response, which makes me think that clients choose which status codes they implement. If that’s true, then I can imagine Twitter’s funny little enhance your calm code being problematic.
Unless I’m mistaken, and we can appropriate any code number to mean whatever we like, and that only convention dictates that 404 means not found, and 429 means take it easy.
The whole of the Internet is built on conventions. We call them RFCs. While nobody will come and arrest you if you violate an RFC, you do run the risk that your service will not interoperate with the rest of the world. And if that happens, you run the risk of your startup not getting any customers, your business getting bad press, your stockholders revolting, your getting laid off permanently, etc.
HTTP status codes have their own IANA registry, each one traceable back to the RFC (or in one case, I-D) that defined it.
In the particular case of Twitter’s strange 420 status code versus the standard 429 status code defined in RFC 6585, the most likely explanation is that the latter was only recently defined; the RFC dates to April 2012. We see that Twitter only uses 420 in the previous deprecated version 1 of its API; the current API version 1.1 actually uses the 429 status code. So it’s clear that Twitter needed a status code for this and defined their own; once a standard one was available they switched to it.
Best practice, of course, is to stick as closely to the standards as possible. When you read RFCs, you will almost always find words like “MUST” and “SHOULD”; these have specific meanings when you are building your application, which you can find in RFC 2119.
1
This question delves into the issue a bit. But the thing is, while you can technically create any status code you want, creating a status code outside of the traditional scope of status code meanings only makes your API more obtuse and arcane to others. Unless that is the point, and the API you are creating is so utterly amazing that everyone will gladly change their coding to follow your lead so what does it matter anyway right?
It boils down to this: Any standard can be broken. But if you break it what do you gain or lose by doing so?
In general, in cases where you can do something different but the standards imply standards, it is best to adhere to the standards unless there is a very strong and compelling reason to veer away from established standards. In the case of Twitter’s 420: Enhance Your Calm they are creating a response code that clearly speaks to a unique situation they face. Which is slowing down requests without denying service.
0