Rate Limiting

To prevent request abuse and to prevent/contain attacks by malicious actors, various controls (Rate Limiting) limit the number of requests that can be made to the API.

These limits may vary depending on the functionality corresponding to a required endpoint.

The algorithm used to limit access, called Token Bucket, is based on the token concept. It specifies the number of tokens requested per endpoint, the token filling rate per second, and the maximum available capacity (burst).

HTTP headers are added to each response received from a limit-enabled endpoint, as in the following example:

X-Ratelimit-Burst-Capacity: 100
X-Ratelimit-Remaining: 99
X-Ratelimit-Replenish-Rate: 2
X-Ratelimit-Requested-Tokens: 1

The example above shows that:

  • the total of available tokens is 100 (X-Ratelimit-Burst-Capacity)
  • the endpoint used consumes 1 token (X-Ratelimit-Requested-Tokens)
  • there are still 99 tokens available (X-Ratelimit-Remaining)
  • the tokens are being replenished at a rate of 2 tokens per second (X-Ratelimit-Replenish-Rate).

Info

The amount of consumed tokens (X-Ratelimit-Requested-Tokens) can vary significantly depending on the endpoint used, for example, some searches may consume more tokens than other features

The application of limits varies depending on whether authentication is required to access the endpoint used:

  • For the public endpoints where authentication is not required, there are limits applied based on the IP address of the requesting client
  • For the endpoints reserved to Registrars where authentication is required, the limits are applied per Registrar and not per user, so the amount of tokens available (X-Ratelimit-Burst-Capacity) is unique regardless of which user of the same Registrar is used to log in.

If the limits are exceeded, you will receive an HTTP response with the code 429 Too Many Requests.

If the number of requests from the same client is huge, network equipment or firewalls may be blocking or limiting the TCP/IP traffic. In these cases, a valid HTTP response will not be returned.