If you make a lot of API requests in a short amount of time, you may bump into the VitalSource rate limit for requests. When you reach the limit, VitalSource stops processing any additional requests until a certain amount of time has passed. This is standard practice to protect both VitalSource and our clients from performance issues and security or DOS threats.
The rate limit for a VitalSource API key is 200 requests per minute per resource or end-point tied to a specific API key. For some of our higher volume end-points, such as our Single Sign-On (SSO) request, the number is significantly higher.
You can monitor your requests for rate limiting problems by inspecting the HTTP response returned after each request. If you get a response code of 429, "Too Many Requests,” you've hit the rate limit and will need to try again after pausing for the recommended time.
In this article we'll cover some best practices for avoiding rate limiting:
- Catching & handling errors caused by rate limiting
- Reducing the number of API requests
- Regulating the request rate
Catching & handling errors caused by rate limiting
It's best practice to include code which catches request errors caused by rate limiting. The HTTP response code VitalSource sends for requests that exceed the number allowed per minute is 429, "Too Many Requests.”
For instance, the HTTP header where the rate-limiting threshold has been hit will return the following information:
HTTP: 429 Too Many Requests
The Retry-After header will tell you how many seconds until the request will work again. You can build logic into your code that will delay or prohibit any additional requests until the time limit has been reached so you do not reset or increase the rate limit block.
Reducing the number of API requests
Make sure you make only the requests that you need. Here are areas to explore for reducing the number of requests:
Optimize your code to eliminate any unnecessary API calls.
For example, are some requests getting data items that aren't used in your application? Are retrieved data items being put back to VitalSource with no changes made to them?
Cache frequently used data.
You can cache data on the server or on the client. You can also save relatively static information in a database.
Regulating the request rate
If you regularly approach or bump into the rate limit, consider including a process in your code that regulates the rate of your requests so that they are distributed more evenly over time. This is known as a throttling process or a throttling controller. Regulating the request rate can be done statically or dynamically. For example, you can monitor your request rate and regulate requests when the rate approaches the rate limit.
To determine if you need to implement a throttling process, monitor your request errors. How often do you get 429 errors? Does the frequency warrant implementing a throttling process?
Is there an end-point that returns all end-points for a resource, including the different rate limits and times to retry?
No, we don't provide a rate-limit end-point.
Will batching calls reduce the number of API calls? How about making parallel calls or using side loading?
No, batching and side loading won't reduce the number of API calls.