We have two API call rate limiting schemes in use with Dotdigital APIs:

• Flat rate limiting - This is our original rate limiting and is based on a given number of API calls per hour.
• Tiered rate limiting - This is our preferred rate limiting and is based on API calls being in a tier with its own rate limit per minute.

The call rate limiting scheme to be used is determined by the API user making the call to the API. Each API user is assigned a call rate limiting scheme when it is created, however you can change this at a later date by editing the API user. Below you can see the API user page and and the Rate limiting option which defaults to the tiered rate limiting:

What rate limiting scheme should I choose?

We recommend using the Tiered rate scheme wherever possible, as it allows you to make more API calls and uses industry standard methods to indicate when you need to reduce usage, so is easier to work with. We offer the Flat rate limit scheme mainly for backwards compatibility with integrations that have been designed to work with it. However, most integrations also work happily with the Tiered rate scheme, so we recommend trying this first and then reverting to the Flat rate limit scheme if necessary.

How do I find my rate limits?

Rate limits are set and tracked at an account level and can be found by doing the following:

1. Log in to Dotdigital with your normal login credentials.
2. Expand the User menu in the bottom left and go to Settings > Access > API rate limits

3. Your Tiered rate and Flat rate call rate limits will be displayed for your account.

Tiered rate scheme

How does it work?

Each Dotdigital API call is categorised into one of the following call rate tiers:

Each of the rate tiers has a set call rate limit which is calculated every minute. Each tier is tracked separately, so exhausting the number of calls in one tier does not stop calls to another tier.

The rate limits apply across the entire API estate, so calls to a Low tier API call on the Contacts service affect how many calls you can make to a Low tier call on the Insight data service.

The actual rate limits for each tier varies based on your account package or any other agreed limits you have. Contact your Customer Success representative to discuss or amend these.

How do I know what tier an API call is in?

All of our API calls are listed in our reference section, and you can see one of the following call rate indicators in the description for the call; this denotes the tier the call is classed in:

Do you provide any feedback on the rate limits?

If you call our API using an API user that has had the Tiered rate limiting scheme enabled, then we provide feedback on the the current state of the rate limits for the tier the call is within via HTTP headers in the response:

• X-RateLimit-Limit - The number of allowed requests in the current rate window.
• X-RateLimit-Remaining - The number of remaining requests in the current rate window.
• X-RateLimit-Reset - The UTC epoch time for when you can make your next call to this tier.
• X-RateLimit-Scope - Which tier this rate limit information applies to, one of:
  • lowCallRate
  • mediumCallRate
  • highCallRate
  • unlimitedCallRate

For example the headers could look like this:

X-RateLimit-Limit: 150
X-RateLimit-Remaining: 149
X-RateLimit-Reset: 1689946239
X-RateLimit-Scope: lowCallRate

x-ratelimit-limit: 150
x-ratelimit-remaining: 149
x-ratelimit-reset: 1689946239
x-ratelimit-scope: lowCallRate

🚧

Use case insensitive matching

When looking for the rate limiting HTTP headers in the response please ensure you use case insensitive matching as per HTTP/1.x specification.

Also please note if calling the API using HTTP/2 the HTTP headers will be lowercase as per HTTP/2 specification.

What happens if I exceed the call rate?

If you exceed the permitted rate limit for a tier within a minute then a HTTP 429 Too many requests response is returned.

How should I handle backing off?

After receiving an initial HTTP 429 Too many requests response, this response continues to be sent until the next rate limiting period begins, so you should efficiently back off until then with possibly a thread sleep. You can tell how long to sleep for by subtracting the current time in UTC epoch format from the value returned in the X-RateLimit-Reset response header. This gives you the time in seconds until the next rate limiting period begins. If the number is positive, then sleep for this many seconds; if 0 or less you can call again immediately.

If you have implemented the suggested sleep back off described above, then your code will be able to maximize the available call rate limit quotas without thrashing 👍.

Flat rate scheme

There is a call rate limit set per account of API calls per rolling hour. When this limit is reached we prevent further API requests to that Dotdigital account, and return a HTTP 400 response with the following message:

Your account has generated excess API activity and is being temporarily capped. Please contact support. ERROR_APIUSAGE_EXCEEDED

Under normal usage conditions, you should not reach this limit. If you are hitting the limit, you should ensure you are batching your data changes and using our bulk API calls.

Please note: Certain calls are exempt from the call restrictions as we understand they will require frequent calling, such as polling status checks, or are of critical importance, such as updating the opt out status of a contact or sending an SMS or transactional email. Calls that are exempt have this stated in their reference documentation, otherwise assume the call limits apply.

How should I handle backing off?

If you do reach the call limit on the flat rate limit, then you can call the Get account information call periodically (we suggest every 2 minutes) and inspect the ApiCallsRemaining returned value, and if greater than 0 you can resume calling.

🚧

We do reserve the right to slow down the amount of calls made to the API if we detect unusual usage patterns.