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: Im 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.
Should I make up my own HTTP status codes? (a la Twitter 420: Enhance Your Calm)
api design;http
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.