Rate limits

What are rate limits? Rate limits are the amount of calls you can make within a certain time span. Rate limits are specific to your plan:

  • Free: 1 call / minute
  • Basic: 1 call / second
  • Pro: 10 calls / second
  • Expert: 20 calls / second

Blocks & duration

TAAPI.IO’s rate limits are “elastic”, meaning that, it’s possible to exceed the limits to a certain extend. But if (when) you get blocked, the general rule is that you get a “fixed time” + “a variable time” based on the amount of exceeded calls, as block time.

The “fixed” block time periods are as follows:

  • Free: 10 minutes
  • Basic: 5 minutes
  • Pro: 3 minutes
  • Expert: 2 minutes

For instance. If you’re a free user, and you squeeze in 7 calls very fast, then you will be blocked:

blockTime = 10 minutes + 7 minutes = 17 minutes

The API will respond with a 429 status code, with the following response (as an example):

{ error: 
   { message: '429: You have exceeded your request limit (TAAPI.IO rate-limit)!',
     maxHitsAllowed: 1,
     maxHitsTimeframe: '1m',
     blockTime: '1020 seconds',
     reason: 'Rate limits exceeded!' } }

The higher the plan you are on, the lower the variable block time is.

Hourly blocks

On top of the above “regular” rate limits, there is an additional upper hourly limit. These limits are also plan specific and as follows:

  • Free: 60 calls / hour
  • Basic: 500 calls / hour
  • Pro: 5.000 calls / hour
  • Expert: 10.000 calls / hour

In case of an hourly block, the API will also respond with a 429 status code, and (example) response:

{ error: 
   { message: '429: You have exceeded your request limit (TAAPI.IO rate-limit)!',
     maxHitsAllowed: 1,
     maxHitsTimeframe: '1m',
     blockTime: 'Rolling unblock',
     reason: 'Hourly rate limit exceeded!' } }

The reason for these hourly limits are to limit a “continuous” stream of calls. If you really need to be able to make 36.000 calls / hour (pro plan), then shoot us a message, and we’ll have a look at it.

The hourly rate limits works slightly different than the regular limits. These limits are “flushed” an hour later as they come in. So, if you get this hourly block, then adjust your call frequency, and wait an hour for the rate limits to completely flush out.

That’s it! If you have any questions or comments, please get in touch!