Subject: Re: API Rate Limits and HTTP Code [#255]

From: Julian Reschke <[email-masked]>
Date: Wed, 22 Jun 2011 13:56:39 +0200

On 2011-04-06 00:10, Mark Nottingham wrote:
> OK. I think we're getting into wordsmithing here; I'll include this as editorial input and see where they take it.
>
> Cheers,
>
>
> On 06/04/2011, at 7:35 AM, Adrien de Croy wrote:
>
>>
>> Why not just say something like
>>
>> "The server is currently unable or unwilling to handle the request."
>>
>> Then give some explanatory text such as:
>>
>> "The server may be prepared to handle the request if resubmitted after a delay.  This is intended to be used for conditions including:
>>
>> * temporary overloading
>> * server maintenance
>> * client rate limiting
>> * any case where service is temporarily unavailable.
>> "
>>
>> the point I'm trying to make is if we define too narrowly the reasons why the code should be used, it will just invite issues later on when people search for an appropriate code to use for their new application which we didn't think about. where really the code just means "not right now".
>> ...

OK, I started with Mark's text but slightly rephrased it to clarify that 
the given reasons are just examples. The section now reads:

8.5.4.  503 Service Unavailable

    The server is currently unable or unwilling to handle the request due
    to reasons such as temporary overloading, maintenance of the server,
    or rate limiting of the client.

    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 field (Section 9.7).  If no
    Retry-After is given, the client SHOULD handle the response as it
    would for a 500 response.

       Note: The existence of the 503 status code does not imply that a
       server must use it when becoming overloaded.  Some servers might
       wish to simply refuse the connection.

(<http://trac.tools.ietf.org/wg/httpbis/trac/changeset/1310>)

Best regards, Julian