To ensure consistent performance and stable access for all users, Optimove enforces API rate limits. This protects our services from excessive load and ensures a high-quality experience for everyone. This article explains what rate limits are, how they work, and how you should handle them in your application.

How Rate Limits Work

Optimove measures rate limits per API Key over a sliding time window. When the number of requests from a single API Key exceeds a limit, the API will stop processing further requests until the window resets.

When a rate limit is exceeded, the API will return an HTTP 429 Too Many Requests status code.

What is a `429` Response?

Status Code: 429 Too Many Requests
Meaning: Your application has sent too many requests in a given amount of time and has been temporarily rate-limited.
Recommended Action: Your code should handle this response gracefully. The best practice is to stop making requests and implement a retry mechanism with an exponential backoff strategy.

Example429 Response Body:

{
  "status": 429,
  "error": "Too Many Requests",
  "message": "You have exceeded the rate limit for this API group. Please retry later."
}

Rate Limits by Endpoint

Rate limits can vary between different endpoints based on their function and resource intensity.

General API Rate Limit

The standard rate limit for most API endpoints is 50 requests per 10 seconds (equivalent to 18,000 requests per hour).

Excluded Function: `SendTransactionalMail`

Calls made to the SendTransactionalMail function are excluded from the general rate limit to facilitate the timely delivery of transactional emails. However, this function has its own specific rate limit:

Limit: 10 calls per second.
Note: Each call to SendTransactionalMail can include up to 200 email recipients.

Best Practices for Handling Rate Limits

To build a robust and reliable integration, we recommend the following practices:

Implement Retry Logic: Use an exponential backoff algorithm to automatically and gracefully handle 429 errors. This involves waiting for progressively longer periods before retrying a failed request.
Monitor Your Usage: Keep track of your API request volumes and monitor for 429 responses to ensure your application stays within the limits.
Batch Requests: Where possible, combine multiple operations into a single request instead of sending many small ones (e.g., the SendTransactionalMail function supporting up to 200 recipients per call).
Cache Results: Store responses for frequently requested data that does not change often to avoid making redundant API calls.
Stay Updated: Subscribe to the Changelog RSS feed to stay informed about any future changes to our API, including rate limits.