Rate Limits
In this page, we describe the Criteo API rate limit policy, and provide you with a few best practices to help manage rate limit within your platform.
Introduction
The Criteo API enforces a rate limit, which consists of a limitation in the number of calls you're able to perform on any of its endpoints.
This limitation is enforced to provide all our API clients with stability towards our API infrastructure.
Rate Limits
Criteo provides different rate limits depending on the OAuth method used by your application.
| OAuth Method | Rate limit | Rate limit applies at level |
|---|---|---|
| Client Credentials | 250 calls per minute | Application level |
| Authorization Code | 35 calls per minute | Access token level |
Rate limit exceptions
Note that some resource-sensitive endpoints may have specific rate limits applied at the endpoint level.
Response
If your application access token exceeds the given rate limit, you will receive a 429 HTTP response and be blocked from executing the action.
The following information will be provided in the header:
| Header | Description | Example response with a limit set at 20 calls/minute |
|---|---|---|
x-ratelimit-limit | the currently authorized limit for this caller | 20 |
x-ratelimit-remaining | the remaining calls for this caller (so, limit - current rate) | 0 |
x-ratelimit-reset | the timestamp at which a new call could be performed | 1628249355 |
Rate Limit Best Practices
For the best experience, while using Criteo API, we strongly encourage implementing best practices methods to help you attain the best API experience.
In the steps below, we will provide guidance to help you manage your application rate limits.
Implement Backoff Mechanics
Exponential backoff mechanisms helps your application handle rate limit exceeded errors by introducing increasing intervals between retry attempts. This approach reduces the likelihood of overwhelming the API server with repeated requests, mitigating the risk of rate limit penalties.
By gradually increasing the time between retries, exponential backoff allows the server to recover from transient failures or temporary congestion more effectively.
In the event that your application runs into a 429 error, we recommend your application waits one second before retrying the call again. When a second error is experienced, have your application wait two seconds before attempting a new retry.
Setting your application to gradually repeat these exponential backoff mechanisms will allow the server to recover from an overload of calls.
Distribute load using access token best practices
Client Credentials
Managing a platform with multiple concurrent users using client credentials can be challenging when maintaining a stable rate limit. This is because client credentials rely on a single access token, which can severely constrain the number of calls your application can make as the number of concurrent users increases.
For example, if you have ten users logged in concurrently, the rate limit maximum for your platform would be 250 calls per minute. This means that each user can only make about 25 calls per minute (250 divided by 10).
During peak hours, when more concurrent users are logged in, this number will decrease significantly, affecting the performance of your platform. However, with the right approach, you can ensure that your platform remains stable, even with many concurrent users logging into your platform.
Authorization Code
Self-service platforms provide users with a convenient way to manage their own data. However, when an application owner handles the data of multiple owners, it is important to segregate data so that each user can only access their own information.
To accomplish this, the platform must manage different access tokens. Criteo has developed an approach that gives each consenter their own token and rate limit. The number of calls from each access token (or consenter) is accounted for and compared to the rate limit separately.
By selecting the authorization code workflow for your application, you ensure that one user's activities won't impact others throughout the platform, creating a stable environment that enhances the user experience.
Export only the data you need, and avoid unnecessary calls
We understand that having the most up-to-date data is essential to help advertisers make the best decisions. But in this section, we will explain how calls to analytics APIs may be unnecessary and can cause your access token to exceed its limits.
Limit your queries to attribution settings users most often look at, instead of pulling all potential combinations of settings
- Pulling all possible attribution settings will increase your needed API calls. Instead of pulling all combinations, allow users to draw the most commonly used settings
Limit your queries to four (4) days of consecutive data
- Pulling more than four (4) days worth of data may be unnecessary, as data won't change beyond this period. Spend and attribution data are both final after 72 hours. Attributed sales are assigned to days on a sale-day basis, not event-day. So, multiple reporting calls can be reduced to ensure that you're getting just the data that you need to cache within your system.
Use bulk operations
- The analytics API also supports Bulk Calls for reporting. API calls can be structured to pass up to fifty (50) campaign or line-item IDs at a time to retrieve the data for each account. Private market retailers will also have the option to use bulk operations to pull data across multiple accounts. If you're a supply account partner, reach out to your account representative to get set up with this feature.
Updated 5 months ago