Subject: API Rate Limits and HTTP Code

From: Karl Dubost <[email-masked]>
Date: Thu, 28 Oct 2010 16:50:43 -0400

Hi,

I have seen a few times blog post (example [1]) over API Rate Limits and HTTP response code. People designing APIs have difficulties it seems to find the appropriate HTTP response code. That led me a few weeks ago to look at what was done at a few services (not a complete survey, just curiosity)

There is no common practice around that. Should the HTTP specification have a specific code for this, or is there already everything appropriate?

[1]: http://mehack.com/inventing-a-http-response-code-aka-seriously
[2]: http://lists.w3.org/Archives/Public/www-archive/2010Oct/0000
[3]: http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-12#section-8.4

-- 
Karl Dubost
Montréal, QC, Canada
http://www.la-grange.net/karl/

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 29 Oct 2010 11:33:10 +1100

Hi Karl,

That's a very timely question; I've had similar discussions privately with a number of folks, and have created an issue to track it:
  http://trac.tools.ietf.org/wg/httpbis/trac/ticket/255

My personal feeling is that we should clarify one of the existing status codes to include this use case, allowing space for someone to define an additional header or two giving more information. I'm happy to be argued into a new status code, but don't think it's necessary at this point.

Based on the links below, it looks like common practice is to use either 403 or 503. 

The commonly cited case for 4xx codes (also explained in the blog you link to) is that it's a client error, not a server error. While I agree generally, it's important to keep in mind the effects on clients. 403 (and any 4xx error that a client doesn't recognise) will result in a conservative client believing that they're not allowed to resubmit the request, whereas 503 + Retry-After results in the correct client behaviour.

That said, I'm more interested in coming to an agreement and assuring that existing software doesn't get broken than in coming up with "perfect" semantics. To that end, it looks like our options are:

a) Clarify that 503 can be used for rate limiting, or

b) Clarify that 403 can be used for rate limiting, and allow Retry-After to appear there, or

c) Define a new status code (4xx or 5xx TBD).

Some other folks doing similar things:

Github uses 403:
  http://support.github.com/discussions/site/1151-api-returns-403-when-rate-limiting

BaseCamp uses 503:
  http://developer.37signals.com/basecamp/

Google seems to use 404:
  http://groups.google.com/group/google-base-data-api/browse_thread/thread/cb5752b43b030fed

Amazon appears to use 503:
  http://developer.amazonwebservices.com/connect/message.jspa?messageID=142896

Apache mod_limitipconn uses 503:
  http://dominia.org/djao/limit/contrib/sbarta/mod_limitipconn.c

Lighttpd mod_evasive uses 403:
  http://redmine.lighttpd.net/projects/lighttpd/repository/entry/trunk/src/mod_evasive.c

... as does Apache mod_evasive:
  http://www.zdziarski.com/blog/?page_id=442

Nginx uses 503:
  http://wiki.nginx.org/NginxHttpLimitZoneModule

Yahoo uses 403:
 http://developer.yahoo.com/search/rate.html

I see references to Facebook using 341, e.g.,:
  http://forum.developers.facebook.net/viewtopic.php?pid=245966

Mozilla Weave doesn't specify a status code, but re-specifies Retry-After:
  https://wiki.mozilla.org/Labs/Weave/Sync/1.0/API#X-Weave-Backoff

--
Mark Nottingham   http://www.mnot.net/

---

From: "Eric J. Bowman" <[email-masked]>
Date: Thu, 28 Oct 2010 19:45:16 -0600

> a) Clarify that 503 can be used for rate limiting, or

+1

I just came across this issue, too, but didn't bookmark -- Twitter's
Fail Whale is a 503; now cute rate-limit responses are proliferating,
but not everybody agrees on what status code to use, which surprises me.
I always assumed rate-limiting was kinda the whole point of 503.

-Eric

---

From: Willy Tarreau <[email-masked]>
Date: Fri, 29 Oct 2010 07:58:31 +0200

> I always assumed rate-limiting was kinda the whole point of 503.

I agree that 503 could match this purpose but I have a problem with using
503. It's commonly tracked in logs to look for service faults (eg: unavailable
server/service). Reusing it as a "normal error" can make this tracking a lot
more complex. In my opinion, 503 really means the service is down (possibly
for a limited time as reported with Retry-After) while here we're more likely
saying "I have a limited capacity, please take your ticket and wait a bit",
which is more about congestion control. Perhaps a new 5xx would fit ?

I'm even thinking we might also like an equivalent in the 1xx response codes,
with the connection remaining open, in the same vein we have 100 Continue.
We could imagine something like "102 please hold the line" once in a while,
indicating that the service is not dead, finally followed by the real
response. It would be really nice for traffic serialization.

Willy

---

From: Juan M. Sierra Lebrón <[email-masked]>
Date: Fri, 29 Oct 2010 09:56:02 +0200

We send this mail from a law firm.
We are not interested in receiving emails advertising.
Under Law 34/2002 of 11 July, Services of information society and electronic commerce, you are notified about the responsibility that you may incur if you keep sending emails.
We want that our data are deleted from its database
Sincerely.

EVIAL ASESORES
Juan M. Sierra Lebrón
[email-masked] 
C/ Pau Claris, 190 - 2º 1ª  -  08037 Barcelona
Telf. 935 157 234 -  Fax 934 873 677

Cláusula confidencial
El contenido de este mensaje y cualquier documento adjunto al mismo son confidenciales. Tienen el sólo propósito de su uso por el individuo o entidad designado como receptor. Si recibe este mensaje por error, se le informa, que su lectura, divulgación, copia o distribución está estrictamente prohibida y le rogamos nos lo notifique por e-mail a ([email-masked]).
 Antes de imprimir este e-mail, piense bien si es necesario hacerlo.

-----Mensaje original-----
De: [email-masked] [mailto:[email-masked]] En nombre de Eric J. Bowman
Enviado el: viernes, 29 de octubre de 2010 3:45
Para: Mark Nottingham
CC: Karl Dubost; HTTP Working Group
Asunto: Re: API Rate Limits and HTTP Code [#255]

+1

-Eric

---

From: Juan M. Sierra Lebrón <[email-masked]>
Date: Fri, 29 Oct 2010 09:56:33 +0200

EVIAL ASESORES
Juan M. Sierra Lebrón
[email-masked] 

Cláusula confidencial

-----Mensaje original-----
De: [email-masked] [mailto:[email-masked]] En nombre de Willy Tarreau
Enviado el: viernes, 29 de octubre de 2010 7:59
Para: Eric J. Bowman
CC: Mark Nottingham; Karl Dubost; HTTP Working Group
Asunto: Re: API Rate Limits and HTTP Code [#255]

Willy