Rate limiting

As a means to protect against abuse, we employ rate limits on the Management API.

All end-points do not necessarily share the same limits. The headers on each response will inform you about your alloted quota and tell you how to handle blocked request.
We use a rolling time window with burst tolerance. This means that after a tolerated short burst of requests, the imposed rate is smooth. Moreover, it avoids you having to wait a full time window if you've consumed all your allowed request in a very short burst, only to exhaust it again with another burst right after.

In short: if you're answered with a 429 Too Many Requests HTTP error, wait the number of seconds you read from the Retry-After header and try again.

Let's take an example of an hypothetical call that is rate limited to 30 requests in a 60 seconds time window with a tolerance of 15 requests in a burst.
Note that as we use a rolling time window it's equivalent to a 15 request burst tolerance with a steady pace of 1 call every 2 seconds. That's why we never explicitly say what the time window is.

Accepted requests

In the response to an accepted request, you will find the following headers in the response:

Header	Description
`X-RateLimit-Limit: 15`	How many requests you are allowed to perform overall in the time window.
`X-RateLimit-Remaining: 5`	How many requests you have left during the time window. Let's pretend we've already used 10 requests, we have 5 left.
`X-RateLimit-Reset: 20`	How long will your quota take to refill to its maximum allowed value. In 20 seconds we will regain 10 requests, and the number of remaining requests will have reached the maximum number of requests we are allowed.

Blocked requests

In the response to a blocked request, you will find the following headers in the response:

Header	Description
`429 Too Many Requests`	Your call has been refused with an HTTP status code of 429.
`X-RateLimit-Limit: 15`	How many requests you are allowed to perform overall in the time window.
`X-RateLimit-Remaining: 0`	You have no requests left during the time window.
`X-RateLimit-Reset: 30`	In 30 seconds we will regain 15 requests, and the number of remaining requests will have reached the maximum number of requests we are allowed.
`Retry-After: 2`	How long you should wait before retrying your call, in seconds. As the steady pace allows you 1 request every 2 seconds, you will need to wait 2 seconds before your call can be retried.

The body of the response will contain the following:

{
  "error": {
    "status": 429,
    "code": "10006",
    "message": "Rate limit exceeded",
    "rateLimit": {
      "retryAfter": 2,
      "limit": 15,
      "reset": 30
    }
  }
}

The necessary information from the headers is conveniently present in the response body. This enables you to know how to retry your individual calls from a /v1/batch request.