Handling Failures
This document outlines how to handle failures when interacting with the Copyleaks API, specifically focusing on implementing an exponential backoff strategy for retrying requests.
Understanding Failure Responses
Section titled “Understanding Failure Responses”When making requests to the Copyleaks API, you may encounter various HTTP status codes indicating different types of failures. Here are some common ones:
-
Error code 503: Service Unavailable. Typically, this error will appear when Copyleaks is undergoing a maintenance period. You can be notified for these events using Copyleaks Status by subscribing to alerts. We broadcast a message days prior to the event time so users will be able to make preparations in advance.
-
Error code 5xx: Internal errors. There is an issue pertaining to Copyleaks’ service and\or the network.
-
Error code 429: Too many requests. Copyleaks, like other REST API services, has a rate limit policy that defines the maximum calls that can be made. Exceeding the maximum calls repeatedly will lead to temporary/permanent blocks.
Suggested Retry Strategy
Section titled “Suggested Retry Strategy”Exponential backoff is a standard algorithm that helps applications define a retry strategy for consuming a network service.
For these status codes mentioned above, we recommend implementing a retry algorithm by doing the following:
- Make a request to the Copyleaks API.
- If the requests fail, wait 1 +
rand_seconds_numberseconds. Then, retry.
- If the requests fail, wait 2 +
rand_seconds_numberseconds. Then, retry.
- If the requests fail, wait 4 +
rand_seconds_numberseconds. Then, retry.
- …
- And so on, up to
max_timeseconds.
- Wait
max_timeand retry up to a limit of n times.
Definitions:
Section titled “Definitions:”rand_seconds_number - Is a random number to add to the wait time. This is to prevent multiple clients from retrying at the same time, which can lead to a thundering herd problem. Suggested values is between 1 and 10 seconds.
max_time - Is the maximum number of seconds to wait. Suggested value is 60 seconds.