How to throttle clients in a REST API

Question

I want to limit clients to an upper limit of number of calls to my REST APIs. What should I return to inform clients that they've been throttled?

Amazon S3 is returning HTTP 503 with an error code SlowDown to inform clients.

What do you advise?

Answer 1

Since RFC 2616 documents status 503 as (my emphasis):

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header.

it seems a reasonable approach, especially with a Retry-After header.

Answer 2

For this case it doesn't seem server is overloaded yet, its just a proactive measure to tell the client that you shouldn't send more than x request in some time. HTTP 503 seems to me as over apologetic to the client, while there is no issue with the server yet and still wining about overload to the client. In my humble opinion its kind of client sending too many request and client is at fault so HTTP 421 seems most appropriate HTTP response code for the case.