420 Enhance your calm

The 420 Enhance Your Calm status code is an unofficial extension by Twitter.

Twitter used this to tell HTTP clients that they were being rate limited. Rate limiting means putting restrictions on the total number of requests a client may do within a time period.

For Twitter it was useful enough to extend the protocol with a new HTTP status code. However, adding your own HTTP status codes is a bad idea and should generally be avoided.

In many cases it’s possible to express your error condition through one of the exiting status codes. Error statuses that are more unique to your application should simply be communicated via a response body. (for example the standard application/problem+json response).

So when is a new HTTP status code useful? The general idea is that adding a new code to the list is useful if it’s possible for a generic HTTP client to do something with the response.

The idea of having a standard HTTP code for rate limiting was useful enough to be turned into a real HTTP status, So a few years later, we got the 429 Too Many Requests status code, which Twitter ended up adopting too.

HTTP series

This article is part of a series about the HTTP protocol. Read them all here:

Informational 1xx

Successful 2xx

Redirection 3xx

Client Error 4xx

Server Error 5xx

Web mentions