Be prepared: 3 ways to handle rate limits

Make sure you don’t get caught out

4 min readNov 17, 2016

In general, when you’re writing any software, you should design for failure: assume the worst case scenario and ensure that your design can cope if that situation arises.

Hopefully, this will mean you never have to have that awkward conversation when someone asks you if you backed up your data or took a regular snapshot.

The same goes for rate limits and APIs — you should also assume that, at some stage, you’ll encounter a rate limit with any API you’re using. The Intercom API is no different.

But I don’t have enough traffic!

It’s easy to assume that you don’t have enough traffic for rate limiting to be an issue. However, your traffic may (hopefully!) grow over time and if you’re not prepared, it may be too late to react when you do get throttled.

It’s also a good idea to consider your peak traffic rates — while your overall traffic rates may be low, you might have a few very spiky periods where you encounter a rate limit. If you don’t handle these properly, you could lose valuable data and impact your customers.

Here, I’ll discuss some tips for dealing with rate limits and how you can make sure you’re prepared if and when you hit them. I’ve focused on using the Intercom API specifically, but much of the advice applies to any APIs you may be using.

What happens when I encounter a rate limit?

You can see the details of our rate limiting on the API Reference page but the key thing to bear in mind is that our rate limiting is variable depending on changes such as overall traffic on the platform.

As a result, we recommend that you monitor the limit returned to you as part of the Intercom client, so you’re always aware of what it is.

Also take note of the provided timestamp which indicates when your current rate count will be reset. You can use this to assess when it’s safe to retry your request.

In total, we provide the following in the HTTP 429 response returned when you encounter a rate limit:

3 methods for handling rate limits

1. The basic way

In the most basic case, you can simply use the information Intercom provides in the headers to decide when to stop sending requests. You can do this by checking the remaining number of requests allowed in your current window — when this is below a certain value you can rest until your rate limit is reset.

In the example below we have restricted the app to a rate limit of 5 just to show the output returned — note that we’ve also shown what information is available in the Intercom client and the response for your current rate limits using the Ruby SDK.

Obviously you don’t need to output all this info, but I just wanted to show you what is available in case you want to use it:

And the output from the above code is:

2. A better way: randomization

While the reset option is one way to deal with rate limiting, you may want more granular control over your rate limit handling. For example, you might have a specific retry timeframe that you want to follow and not wait for the minute window to pass for your entire rate limit to be reset.

If you want more control over your rate limiting handling then you can check for the specific rate limit error returned and use some form of randomization in the backoff calculation.

You could change the retry code above to look like this to achieve some randomization:

Your output would then look like this:

3. An even better way: retry gems

If you don’t want to worry about implementing backoff formulas, then the best way to handle rate limiting is with a RubyGem such as retries.

It’s easy — you just specify the number of retries you want and let it do the rest:

Here’s the output from the above example with retries:

Make your choice

Of course, the final choice is up to you, but whichever method you use it’s important to have some way of identifying when rate limiting occurs, how to handle it and also how to be notified when you have reached your max number of retries.

You need to catch the error raised in some other code and store some information to know what data was not processed if you max retries were reached.

Hopefully this post has given you some food for thought. There are plenty of great resources online with more on dealing with rate limits — we recommend this simple backoff example (which I used for some of the above code examples), this post which talks a little bit more about backoff theory and this article which give some standard examples of rate limiting as a good start.

Let us know if you have any questions or suggestions in the comments below, or you can tweet us @intercomdevs.