Handling 5xx Errors & Retries

This best practices guide is designed to help our customers understand why and how to handle occasional 500, 503, and 504 errors that can be encountered while using our APIs. While we make significant attempts to accept and process all API requests to our service, some errors will be encountered from time to time. This guide will attempt to explain the nature of various errors that can be encountered and how best to handle them.

Best Practices for Interacting with VitalSource APIs

Please log all API calls and responses.

Please log your full API requests and our API responses to you. If you encounter an error in using our APIs, we will ask you for your API log data in order to see your API request and our API response to you. This is standard practice to allow us to begin investigation and ultimately provide you with the most accurate solutions to issues that may arise.  

Retry on 500/503 error responses.

A 500 or 503 error means that we did not accept your request for processing and to please try again with an exponential back-off retry method. If your first API call does not succeed, please retry your request. A second attempt will typically succeed. For more information on exponential backoff, please see this Wikipedia article: Exponential backoff - Wikipedia, the free encyclopedia. Generally, we suggest you retry once immediately when encountering a 5xx error. If you continue to receive 5xx errors, scale back the retry based on the above article to another request 3 seconds later, then 5, then 10 seconds.

Some errors are expected.

While we strive for 100% uptime, all the time, we do have occasional errors; other errors could also occur outside of our network somewhere on the Internet itself. If your error rate is less than .5%, a retry is your best path forward. If you feel that VitalSource is experiencing a higher than .5% failure rate, please contact our Support desk.