11

What are permissible requests "speeds?"

The API will cut you off if you make more than 30 requests over 5 seconds to any single endpoint (currently 30 requests per second, https://api.stackexchange.com/docs/throttle).

We consider this a breach of the API interface contract, so you won't get a nice error back. The exact manner in which this constraint is enforced can (and will, in all likelihood) vary over time. Attempts to work around this limit will be consider unconscientious use of the API.

Note that you can stay within this limit and still blow through an entire [app]s quota in less than 1/2 an hour.

9
  • An API is not at fault if they allow requests to take place more than 30 time in 5 seconds, right? Or do we need to build throttling into our API?
    – jjnguy
    Jul 20, 2010 at 2:17
  • 4
    Do you mean "contentious" or "unconscientious", because I think "uncontentious" means the opposite of what you intend. Also s/will be consider/will be considered/. Jul 20, 2010 at 3:14
  • 1
    @dennis - grammar cop ;-) on another note one can be very conscientious while simultaneously being very contentious (looking in mirror) Jul 20, 2010 at 3:21
  • 1
    ++ kevin - you can tag all of the multidunious 503 related questions as status-complete with my unsolicited blessing. Thanks. I can now finalize my libs and release them into the wild. stackapps.com/questions/999 stackapps.com/questions/1043 stackapps.com/questions/1092 Jul 20, 2010 at 3:27
  • kevin - one more to tag complete stackapps.com/questions/999 Jul 22, 2010 at 18:20
  • can you be explicit as to whether the throttle limit applies to each api_endpoint individually or the the api as a whole? we know the answer to this but it should be explicitly stated for those who don't. Jul 28, 2010 at 8:14
  • thank you for the response but i think the word 'single' introduces some ambiguity, at least it does for me and english is my native language. may i suggest something like "30 per 5 from your IP to our IP regardless of endpoint" OR "30 per 5 sec from your IP to each of our endpoints" Jul 28, 2010 at 13:27
  • 2
    a real story to define this concern: I have an app that is working on data from api.stackoverflow on one thread while working on data from api.stackapps on another. Should each thread have a separate throttle or should they share a common throttle? Jul 28, 2010 at 14:05
  • 1
    kevin, your verbage can be interpreted both ways. you need to be explicit when stating terms of service. Jul 29, 2010 at 6:18

2 Answers 2

8

I have confirmed that a constant interval of 170 ms will run without error.

// 30 per 5 sec = 6 per sec =    interval 166.6 ms
Soapi.RequestQueue.setInterval(170);    

Soapi.RouteFactory("api.meta.stackoverflow.com", apiKey)
   .Tags({ pagesize: 1 })
   .getPagedResponse();

will run through all the tags on meta 1 at a time without issue.

This is very much a fix to an elusive problem.

Thanks much and if there is any more clarification you can provide regarding burst allowance and/or the complete lack of burst allowance that would also be appreciated.


"30 requests over 5 seconds" leaves a lot to the imagination.

Does that mean that I can maintain a sustained rate of 6 request per second for a reliable rate of 360 per minute without error which would equal 10800 over a period of 30 minutes?

Is there no burst allowance and if there is, what is the cooldown?

If you could give clear guidelines that everyone can follow without the need to interpret something that can, well, be interpreted in many ways depending on how much experience or knowledge of throttles one may have.

We must construct our client libraries to respect the throttle while providing a nominal request rate and these numbers are crucial to that end, otherwise the apps that are built on them will be brittle.

And when you say 'The exact manner in which this constraint is enforced can (and will, in all likelihood) vary over time.' do you mean that the throttle numbers are going to remain constant but response to a throttle violation will change, or the other way around e.g. are we going to deploy apps and package and distrbute libraries that make every effort to respect the states limits only to have them change without notice?

Please be more specific so as to remove ambiguity and so that we may be more compliant without confusion, guesswork or complaints.

This is a truly critical issue and whatever the final decision/numbers are is fine as long as they are clearly defined.

Sincerely, Sky Sanders

11
  • 1
    It should be pretty simple. If at any time you have made more than 30 requests within 5 seconds, you have violated the terms of using the api.
    – jjnguy
    Jul 20, 2010 at 3:00
  • 1
    @jjn - are you somehow opposed to a formal spec that can be codified and complied without ambiguity? Jul 20, 2010 at 3:08
  • @code What I'm against is wasting the devs time on an unnecessarily complex specification.
    – jjnguy
    Jul 20, 2010 at 3:11
  • @code, also to this point - "We must construct our client libraries to respect the throttle while providing a nominal request rate and these numbers are crucial to that end, otherwise the apps that are built on them will be brittle." I don't think it is our job to provide throttling in the library. Unless you provide some library call that has the potential of making multiple calls to the api.
    – jjnguy
    Jul 20, 2010 at 3:13
  • (cont) In that case, make sure you wait 1/6 of a second between requests.
    – jjnguy
    Jul 20, 2010 at 3:13
  • 1
    @jjn - we may have different ideas of how a library should abstract details like this away from the casual or hobbyist consumer, but in any case, I have already implemented a throttled queue as well as request caching in all of my libraries, which is not trivial if to be done properly, and just need some clearly defined numbers to plug in to them. An interval of 170ms does indeed seem to be the magic number and is actually much better than I was expecting. I am happy. Are you happy? YAY! everyone is happy and can relax. Jul 20, 2010 at 3:36
  • @code, I am happy...and relaxed...and gonna look into creating a throttled queue for my api.
    – jjnguy
    Jul 20, 2010 at 3:47
  • @jjn - don't forget a min 60 sec cached buffer - it does wonders for responsiveness and throttle compliance Jul 20, 2010 at 3:58
  • 1
    "30 requests over 5 seconds" is exactly what I mean. 30 requests within 5 seconds, clustered however. That could be 1 every 6th of a second, or 30 right up front. Jul 20, 2010 at 4:20
  • 1
    "The exact manner in which this constraint is enforced can vary over time" means that the API will respond however we feel like if you break the request spacing invariant. This could be a 503, it could mean we just close the underlying TCP connection. Any response is a "correct" one. Of course we aren't going to change the "30 over 5" part, as that would defeat the point of spec'ing it in the first place. Jul 20, 2010 at 4:22
  • @kevin - perfect - that is exactly what I was hoping for. Jul 20, 2010 at 4:25
1

I am not sure if it has fallen off the radar or if it is an honest oversight but we can't seem to get an explicit description of the throttling guidelines.

Core issues like this are critical, especially for library developers, and care should be taken to be as explicit as necessary to clearly define the guidelines.

Case in point:

My lazy loading library uses a gateway that is cached and throttled.

If the throttle limits are calculated globally, I will return a common gateway from the gateway factory that all requests are routed through, resulting in a max of 6 requests per second from my IP to your IP.

if the throttle limits are calculate per endpoint, I will return a distinct gateway for each endpoint, resulting in a max of N * 6 requests per second from my IP to your IP.

This is why it is important to be as explicit and detailed as necessary in order for a reasonable person to be clear on the guidelines.

casual documentation of core issues that can result in systemic failure of libraries and/or banning of IP/Keys is not responsible stewardship.

And if there are those that think I am just being contentious, let me assure you that I and several other professionals are very wary of building anything on top of this API due to the lack of professional response to mission critical issues such as this.

9
  • 1
    @code, I think the language you use is very condescending. I feel like you are talking above everyone else. No one else seems to have problems with this.
    – jjnguy
    Jul 29, 2010 at 14:50
  • 1
    Read this quote carefully: "The API will cut you off if you make more than 30 requests over 5 seconds to any single endpoint." So, your api can make N * 6 requests per second. Where N is the number of routes. This assumes you are spreading your requests equally over each endpoint.
    – jjnguy
    Jul 29, 2010 at 14:51
  • (To be fair, that was only added yesterday, and now I have to re-do my throttling code...)
    – jjnguy
    Jul 29, 2010 at 14:54
  • 1
    i appreciate your feedback, @jjn, but i have read it carefully and while it certainly may be interpreted as you say, it could also be seen to imply that a request to any single endpoint can count towards your 6ps quota. are you picking up on what i am putting down? there are people courting investors for technology based on the data api and it is things like this that leave far too much to chance. you might want to shift your perspective a bit to understand how my initial attempts to get codification failed and resulted in this post. check the timelines. Jul 29, 2010 at 15:03
  • 1
    I see where the ambiguity lies. Does it mean that any call to a route will count towards the total, or will it count 5/30 for each route separately?
    – jjnguy
    Jul 29, 2010 at 15:06
  • i am not the person to ask, @jjn. this information must come from a representative of SO. you and i can wax poetic and postulate ad infinitum but it is nothing more than entertainment. Jul 29, 2010 at 15:16
  • @jjn - see update for some context as to why I am so intent on having unambiguous specifications. Jul 29, 2010 at 16:27
  • 2
    @jjnguy - I'm glad there is already some agreement here, but to put @code poets engagement into perspective I'd like to add that I don't think his language is condescending (I'm not a native speaker though) and I'm definitely having problems with this and similar issues as well. Code has tackled an enormous amount of issues and gone to great length to work around various existing problems better addressed at the API level already to save others the effort. The least we could expect is to get some timely acknowledgment for issues almost always raised politely and in good faith. [continued ...] Jul 29, 2010 at 23:54
  • 2
    [... continued] The responsiveness of the Stack Exchange team leaves much to be desired though, and I fail to understand what's so hard about saying We'll look into this later at least. This is indeed a major impediment from a professional perspective and does apply to non technical issues as well, see here for an example: again a user (me) is even willing to invest a considerable amount of time eventually to work around a limitation of the API, just like code poet here, but I'm getting ignored and am unable to proceed in good faith therefore! Jul 29, 2010 at 23:54

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .