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

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

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:
  1. Make a request to the Copyleaks API.
  2. If the requests fail, wait 1 + rand_seconds_number seconds. Then, retry.
  3. If the requests fail, wait 2 + rand_seconds_number seconds. Then, retry.
  4. If the requests fail, wait 4 + rand_seconds_number seconds. Then, retry.
  5. …
  6. And so on, up to max_time seconds.
  7. Wait max_time and retry up to a limit of n times.

​
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.

​
Next Steps

Webhooks Overview

Learn how to use webhooks to receive real-time notifications about scan statuses, including failures.

Technical Specifications

Review the technical specifications, including rate limits, to optimize your API usage.

Authenticity API Overview

Explore the comprehensive Authenticity API for managing your plagiarism and AI detection processes.