HTTP REST Status Code – Suggested Code for ‘Request Limit Reached’

httprestweb services

I'm putting together a spec for a REST service, part of which will incorporate the ability to throttle users service-wide and on groups of, or on individual, resources. Equally, time-outs for these would be configurable per resource/group/service.

I'm just looking through the HTTP 1.1 spec and trying to decide how I will communicate to a client that a request will not be fulfilled because they've reached their limit.

Initially I figured that client code 403 - Forbidden was the one, but this, from the spec:

Authorization will not help and the request SHOULD NOT be repeated

bothered me.

It actually appears that 503 - Service Unavailable is a better one to use – since it allows for the communication of a retry time through the use of the Retry-After header.

It's possible that in the future I might look to support 'purchasing' more requests via eCommerce (in which case it would be nice if client code 402 - Payment Required had been finalized!) – but I figure that this could equally be squeezed into a 503 response too.

Which do you think I should use? Or is there another I've not considered?

Best Answer

429 Too Many Requests

The user has sent too many requests in a given amount of time. Intended for use with rate limiting schemes. This code has been accepted in RFC 6585 Additional HTTP Status Codes.

http://i.stack.imgur.com/Y84Lj.jpg

   The 429 status code indicates that the user has sent too many
   requests in a given amount of time ("rate limiting").

   The response representations SHOULD include details explaining the
   condition, and MAY include a Retry-After header indicating how long
   to wait before making a new request...

   Note that this specification does not define how the origin server
   identifies the user, nor how it counts requests.  For example, an
   origin server that is limiting request rates can do so based upon
   counts of requests on a per-resource basis, across the entire server,
   or even among a set of servers.  Likewise, it might identify the user
   by its authentication credentials, or a stateful cookie.

   Responses with the 429 status code MUST NOT be stored by a cache...
Related Topic