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?
2 Answers 2
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.
https://i.sstatic.net/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...
-
Sounds awesome - I'll keep it in mind! Does it come with free cats? Or are they an extension to the protocol?Andras Zoltan– Andras Zoltan2012年01月06日 09:50:38 +00:00Commented Jan 6, 2012 at 9:50
-
3HTTP Status cats -- for all your status needs: flickr.com/photos/girliemac/sets/72157628409467125Sean McMillan– Sean McMillan2012年01月09日 13:21:50 +00:00Commented Jan 9, 2012 at 13:21
-
1that has just gone round the office to much laughter and applause - genius!Andras Zoltan– Andras Zoltan2012年01月09日 14:33:11 +00:00Commented Jan 9, 2012 at 14:33
-
I went with a 429 in the end - it's in the draft spec but I seriously doubt it'll end up being used for anything else.Andras Zoltan– Andras Zoltan2012年10月30日 21:55:02 +00:00Commented Oct 30, 2012 at 21:55
To an extent, you're free to do what you like with the codes, but I would agree that you can use 503
, or if you want 402
, without anyone being able to complain that you are breaking things.
Edit: A purist might say that you should start with 503, then switch once it's possible to make payments.
An excellent addition to this in the comments:
A 4xx indicates an error by the client that can be fixed by them taking a certain action, whereas a 5xx indicates a problem on the server that the client can't help resolve. So in your case, a 4xx is more appropriate, because the (i) the server is behaving exactly as it should, and (ii) the client can "fix" the error by either slowing down or purchasing more credits. The exact resolution can be indicated in the body of the 429 response. – Mike Chamberlain 7 hours ago
-
503! 503! 503! Reached the limit, the next call is forbiden. Plain and simple...yannis– yannis2012年01月05日 12:10:07 +00:00Commented Jan 5, 2012 at 12:10
-
@YannisRizos: Ah, but it's not forbidden once the payment has been made!Marcin– Marcin2012年01月05日 12:13:42 +00:00Commented Jan 5, 2012 at 12:13
-
1The error code represents the result of the single request. If the payment was made, then on a subsequent request it's business as usual... If you document the behaviour, it's fine by me. Or you could just return 200, with an error message. But that's not pretty. Although some might say using HTTP error codes for business logic is not pretty. Ah well, I'd personally go with 503, service is not available at this moment - until of course 402 is commonly supported.yannis– yannis2012年01月05日 12:21:55 +00:00Commented Jan 5, 2012 at 12:21
-
@YannisRizos (& Marcin) - thanks for your comments - I figured 503 was the best one to go with; whilst also understanding that implementations of a RESTful nature can often fall foul of being woolly when it comes to their use of HTTP status codes. My personal viewpoint on this is to use what the protocol provides unless it doesn't fit (which is actually very rare). In this case, it definitely does!Andras Zoltan– Andras Zoltan2012年01月05日 12:38:04 +00:00Commented Jan 5, 2012 at 12:38
-
6A 4xx indicates an error by the client that can be fixed by them taking a certain action, whereas a 5xx indicates a problem on the server that the client can't help resolve. So in your case, a 4xx is more appropriate, because the (i) the server is behaving exactly as it should, and (ii) the client can "fix" the error by either slowing down or purchasing more credits. The exact resolution can be indicated in the body of the 429 response.Mike Chamberlain– Mike Chamberlain2016年04月14日 05:46:03 +00:00Commented Apr 14, 2016 at 5:46