Rate limiting

As a means to protect against abuse and ensure a fair sharing of resources, 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 allotted quota and tell you how to handle blocked request.
We use a rolling time window with burst allowance. This means that after a tolerated short burst of requests, the rate is strict, imposing a minimum time between two requests. The process is hence smoothed over time within each passing second, instead of using a granular time window.

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.

The below takes a hypothetical call that is rate limited to 30 requests in a 60 seconds time window with a allowance of 15 requests in a burst. Because we use a rolling time window, it's equivalent to a 15 request burst allowance 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.

Batching endpoints

Endpoints that accept multiple items to work on count as 1 request regardless of the number of work items each request is comprised of. This means that you a request for sending a notification to 1 or many targeted Installation IDs count the same. A batch of 10 or 100 sub-requests count the same.

The POST /v1/batch endpoint has a rate limit of its own, and runs each sub-request within the batch sequentially. Each individual sub-request is still imposed the rate limit corresponding to the called endpoint.

This means that your batch can then be blocked as a whole due to a rate limit on POST /v1/batch, or the batch itself may proceed but a some of the sub-requests may be individually blocked due to a rate limit.

Default rate limits

Here are the default limits we currently apply:

Endpoints	Steady rate	Burst	Replenishes in
Reading and listing objects	100 req over 1 s 10 ms appart	200 req	2 s
Writing and deleting objects	50 req over 1 s 20 ms appart	100 req	2 s
Batching (`POST /v1/batch`)	10 req over 1 s 100 ms appart	10 req	1 s
Sending notifications `POST /v1/deliveries`)	20 req over 1 s 50 ms appart	100 req	5 s
Reading statistics (`/v1/stats`)	10 req over 1 s 100 ms appart	100 req	10 s

Note: We reserve the right to adjust these limits globally or individually in order to protect the service from abuse and ensure a fair sharing of resources between customers.

A steady rate of R requests per S seconds with a burst of B requests means that:

if your burst allowance is full, you can make up to B requests instantly.
if your burst allowance is emptied, the steady state of R/S requests per second applies and imposes requests to be at least S/R seconds appart or they will be blocked.
unless consumed by a request, the burst allowance replenishes at a rate of R/S requests per second up to it maximum of B requests.
an emptied burst allowance takes B×R/S seconds to replenish.