Rate limits

​

Introduction

As the Hub2 API is their main project, a solid quality of service is required.

In order to keep an appropriate latency and a reliable service, rate limits must be enforced on the most cost-heavy endpoints.

This limit is applied per IP address, so it is relative to each of the API users and the usage of one won’t impact the usage of the other.

That is why we enforce those limits.

​

API limits

Here is a table of rate limits. The global limit is for all other endpoints.

​

How to handle limits

Whenever a request is received by the API beyond the limit of the endpoint, an error Too Many Requests with HTTP status 429 will be returned.

The request failed and was not handled by the API because of the rate limit.

Headers are provided in the HTTP response for proper handling :

​

Reactive solution (easier)

One way to handle rate limits from a client-side perspective is to retry requests if they fail for a 429 reason:

const MAXIMUM_TRY_COUNT = 3;
const URL = 'https://api.hub2.io/balance;
const CONFIGURATION = {
  method: "GET",
  headers: {
    ApiKey: MY_API_KEY,
    MerchantId: MY_MERCHANT_ID,
  },
};

(function requestRetry(numberOfTries) {
  fetch(URL, CONFIGURATION)
    .then(() => {
      // code here
    })
    .catch((error) => {
      if (error?.response?.status === 429) {
        if (numberOfTries > MAXIMUM_TRY_COUNT) {
          throw error;
        }

        // Adding 1 second of grace delay
        const retryAfter: number = parseInt(response.headers['retry-after'], 10) + 1;
        await new Promise((resolve) => setTimeout(resolve, retryAfter));
        return requestRetry(numberOfTries + 1);
      }
    })
})(0);

​

Proactive solution (harder)

The proactive solution is a bit trickier, it consist of keeping a pool of requests ready to be started with the exact size of the destination endpoint rate limit. Whenever the pool is empty, the next request waits in line for a token to free up.

Check out that interesting article on how to implement rate limit from the client-side perspective, especially approaches 4 and 4.1.

​

Conclusion

In a perfect world, no limit would be set on the API endpoints. However in the real world, it helps preventing abuse and keep a reliable service for everyone.

The team work on a daily basis to improve the stability and the performance of the API and this page will be updated as soon as upgrades allow to loosen the limits.