Rate Limits - Criteo Docs
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 | Applies at |
|---|---|---|
| Client Credentials | 250 calls/min (default endpoints) 40 calls/min (reporting endpoints) |
Application level |
| Authorization Code | 10 calls/min | Account level |
Rate limit exceptions Some resource-sensitive endpoints, such as reporting endpoints, have stricter rate limits.
For example, reporting endpoints are limited to 40 calls per minute, compared to the default 250 calls per minute.
Auto-Scaling for Authorization Code Applications
The auto-scaling only applies to Authorization Code flow and not Client Credentials.
Authorization Code apps support dynamic rate limits based on the number of accounts each user has consented to:
- Base limit: 10 calls/min per account per user,
- Example: A user who consents to 3 accounts enables 30 calls/min for that app (3 × 10)
Calls are shared across accounts; using all on one affects the others. This allows higher throughput when users consent to more accounts.
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 help 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 handles data for multiple users, it’s crucial to ensure that each consenter (i.e., user who grants access) can only access their own information and is subject to their own resource limits. To support this, Criteo enforces rate limiting per consenter. Each consenter receives a dedicated access token and is assigned an individual rate limit. All API calls made with that token are counted against the consenter’s quota, not a shared or global one. By choosing the authorization code workflow for your application, you ensure that activity from one consenter does not affect the experience of others. This isolation provides a more stable and predictable environment for all users.
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 of data is typically unnecessary, as most spend and attribution data stabilize within 72–74 hours. Minor updates may occur for up to 120 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.
Different types of activity and attribution data become available at different times after the event or sale:
- Onsite activity data is typically available within 6–8 hours of the event.
- Offsite activity data is typically available within 24 hours of the event.
- Initial attribution data is available within 7–9 hours of the sale.
- Final attribution data is processed and posted within 74 hours after the sale.
- Please note that potential minor updates can occur up to 120 hours before finalization
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.