Rate limits

Rate limits¶

All our APIs are rate-limited. If you call them too often, you'll get back a response with a 429 (Too Many Requests) status code. The response JSON is an error object. See the next section for advice on dealing with this error.

To avoid getting this error, callers should space out requests using the following schedule:

The first three limits are for Denial of Service (DoS) protection. Each limit applies equally and separately to each set of API credentials, account, and originating IP. This means you can't split API calls between different API credentials from the same account or use the same API credentials from different IPs to work around the rate limit.

The daily quota applies to each account and each set of API credentials, but not the originating IP.

These rate limits apply globally across all our APIs. Where some API operation enforces an additional rate limit, the details are documented in the API reference. We're unable to customize these rate limits for individual partners or customers at this time.

Retrying on error¶

When an API call fails with the 429 (Too Many Requests) status code or a 5xx (Server Error), we recommend retrying the request after a small period of time. This time interval should be calculated using an "exponential backoff" strategy, adding random "jitter" to each subsequent attempt.

For a in-depth discussion of these terms, see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/.

The following formula (taken from that page) can be used to determine how long to leave between a failed API call and the next one:

backoff = random_between(0, min(cap, base * (2 ** attempt)))

Here:

backoff is the amount of time to intersperse between the failed call and the next one. You can do this by invoking a sleep function in the client code or by doing something else that suspends the execution thread for that period of time.

random_between is a mathematical function that returns a random number between two integers. This function may use a source of randomness that is not cryptographically secure.

min is a mathematical function to find the smaller of two numbers.

cap is the maximum amount of time to leave between two successive API calls.

base is the normal amount of time between two successive API calls. Note this value differs for each API operation.

attempt is the attempt number, 0 for the API call being attempted after the first failure, 1 for the API call attempted after the second failure, and so on.

For example, you can use the following parameters:

base = 1000         # Normally, it's fine to leave 1 second between calls
cap = 30000         # But leave no more than 30 seconds between calls

With the "Full Jitter" strategy, the timeline of API calls may look something like the following.

The caller makes the first API request that fails with 429 or 5xx.

The caller calculates the amount of time to back off by passing in attempt set to 0:

backoff = random_between(0, min(30000, 1000 * (2 ** 0)))

This is equivalent to a random value between 0 and 1000. The API client program or script should not make the next API call until a randomly chosen period of time between 0 to 1000 milliseconds has passed.

Assuming the API call fails again, the backoff is recalculated by passing in attempt set to 1:

backoff = random_between(0, min(30000, 1000 * (2 ** 1)))

The client program or script should not make the next API call for a random period between 0 to 2000 milliseconds.

On the third attempt, backoff is a time interval between 0 and 4000 seconds.

On the fourth attempt, backoff is a time interval between 0 and 8000 seconds.

On the fifth attempt, backoff is a time interval between 0 and 16000 seconds.

From the sixth attempt onwards, the backoff is a time interval between 0 and 30000 rather than 32000, as this is the cap, the maximum backoff value.

Continue this as long as successive API calls fail with 429 or 5xx. If an API call succeeds or fails with a different status code, the API caller should go back to making the next API call as normal, either immediately or with the normal backoff. We recommend limiting the code to a maximum number of retries before giving up and alerting someone to the errors.

Aggregating tenant data¶

As a partner or an organization you need to aggregate data across the tenants you manage. There are a few steps you need to follow.

1. Authenticate
2. Find your Partner or Organization UUID by calling GET https://api.central.sophos.com/whoami/v1
3. List tenants, fetching all pages
   • Partners: GET https://api.central.sophos.com/partner/v1/tenants with the UUID passed in the X-Partner-ID header
   • Organizations: GET https://api.central.sophos.com/organization/v1/tenants, with the UUID passed in the X-Organization-ID header
4. For each tenant, make the specific tenant API call using the tenant's data region and passing the tenant's UUID in the X-Tenant-ID header. Call the API to fetch as many pages as needed
5. Combine the data from different tenants, either aggregating in memory or into a persistent datastore.