Take the 2-minute tour ×
Stack Apps is a question and answer site for apps, scripts, and development with the Stack Exchange API. It's 100% free, no registration required.

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.

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.

share|improve this question
    
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 '10 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/. –  Dennis Williamson Jul 20 '10 at 3:14
1  
@dennis - grammar cop ;-) on another note one can be very conscientious while simultaneously being very contentious (looking in mirror) –  Sky Sanders Jul 20 '10 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 –  Sky Sanders Jul 20 '10 at 3:27
    
kevin - one more to tag complete stackapps.com/questions/999 –  Sky Sanders Jul 22 '10 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. –  Sky Sanders Jul 28 '10 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" –  Sky Sanders Jul 28 '10 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? –  Sky Sanders Jul 28 '10 at 14:05
1  
kevin, your verbage can be interpreted both ways. you need to be explicit when stating terms of service. –  Sky Sanders Jul 29 '10 at 6:18

3 Answers 3

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.

share|improve this answer
2  
downvoting? are you serious? get a clue. –  Sky Sanders Jul 29 '10 at 7:40
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 '10 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 '10 at 14:51
    
(To be fair, that was only added yesterday, and now I have to re-do my throttling code...) –  jjnguy Jul 29 '10 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. –  Sky Sanders Jul 29 '10 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 '10 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. –  Sky Sanders Jul 29 '10 at 15:16
    
@jjn - see update for some context as to why I am so intent on having unambiguous specifications. –  Sky Sanders Jul 29 '10 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 ...] –  Steffen Opel Jul 29 '10 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! –  Steffen Opel Jul 29 '10 at 23:54

Would running two servers with seperate IP addresses be allowed to exceed this limit providing neither exceeds 30 req. / 5 sec. on its own?

share|improve this answer
    
per endpoint, per ip - dem's da rules. –  Sky Sanders Jul 20 '10 at 19:59
2  
Distinct IPs are throttled separately. –  Kevin Montrose Jul 20 '10 at 21:27

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

share|improve this answer
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 '10 at 3:00
    
@jjn - are you somehow opposed to a formal spec that can be codified and complied without ambiguity? –  Sky Sanders Jul 20 '10 at 3:08
    
@code What I'm against is wasting the devs time on an unnecessarily complex specification. –  jjnguy Jul 20 '10 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 '10 at 3:13
    
(cont) In that case, make sure you wait 1/6 of a second between requests. –  jjnguy Jul 20 '10 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. –  Sky Sanders Jul 20 '10 at 3:36
    
@code, I am happy...and relaxed...and gonna look into creating a throttled queue for my api. –  jjnguy Jul 20 '10 at 3:47
    
@jjn - don't forget a min 60 sec cached buffer - it does wonders for responsiveness and throttle compliance –  Sky Sanders Jul 20 '10 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. –  Kevin Montrose Jul 20 '10 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. –  Kevin Montrose Jul 20 '10 at 4:22
    
@kevin - perfect - that is exactly what I was hoping for. –  Sky Sanders Jul 20 '10 at 4:25

You must log in to answer this question.

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