Understand the rate limits in the Digital River API and learn how to handle and avoid reaching these limits
Based on the API key that you include in a request, the Digital River APIs limit the number of calls that you can make within a given time period.
We use this rate limiting to maintain system stability and to ensure that all Digital River API clients experience efficient, secure, and reliable service. Rate limiting also helps us mitigate the damage caused by malicious actors and faulty integrations.
If you exceed the designated rate limit, then your integration should temporarily stop making requests. This is because these requests will fail until a certain amount of time has passed. You can usually avoid hitting this ceiling by following our rate limiting best practices. But, in the event the request limit is breached, your integration should have logic in place to handle rate limiting.
When a request exceeds these rate limits, we block that call from reaching our backend servers. We then send you a response with a
429 Too Many Requestsstatus code and a standardized
Retry-Afterheader. The header value is an integer, representing the number of seconds you should wait before making another request. You can use this value when building your mechanism to handle rate limiting.
The following example shows a partial response to an API request that exceeded the rate limit. The
Retry-Afterresponse header indicates that your integration should delay 2 minutes before sending any more requests.
429 Too Many Requests
Here are some of the more common reasons you might exceed your request rate limit:
- Your ecommerce store might be conducting a flash sale (in which deep product discounts are offered for a short period of time) and this event results in a sudden spike in traffic. In almost all cases, our standard rate limits are high enough so that legitimate traffic is never throttled. However, if you believe that an upcoming event might cause you to hit your request ceiling, then you should contact your Digital River representative and inquire about temporarily increasing your rate limit.
- Making unnecessary requests to the APIs that retrieve data items from the response but then fail to use that data in your application.
The simplest, most straightforward approach is to just build a delay into your code. This means that, whenever you catch a
429error, you should delay the execution of your next API call. The exact number of seconds to delay that call is determined by the value of the
Retry-Afterresponse header. We recommend that you don't make any additional requests until this specified time has elapsed. If you do, those requests will be blocked.
If you're seeking a more sophisticated solution to handling rate limits, you could implement an exponential backoff algorithm. With this approach, after the wait period has expired, you periodically retry a failed request. The wait time between each retry request increases exponentially, up to a designated maximum backoff time. At this point, the time between retries does not need to continue increasing. If you use this approach, we also recommend you code some random behavior, or jitter, into your algorithm's wait times. This helps to avoid scenarios in which many client requests have become synchronized by a blocking event and retry requests are sent in synchronous waves (i.e., the thundering herd problem).
Your integration should always be set up to handle rate limiting. But we also recommend that you attempt to minimize the probability of hitting your request ceiling. In most cases, you can accomplish this by adhering to the following best practices:
- Optimize your code to eliminate unnecessary API calls. For example, ensure that all of your requests are retrieving data and that data is then used by your application.
- Avoid making multiple concurrent requests.
- When you're making a large number of
DELETErequests for a single user, you should implement a delay between each request.