API rate limit

HighQ Collaborate API has no usage limits imposed on it in version 1 of the API release with Collaborate 3.4.x, which means that any API consumer can send as many request as they want to our servers, which can have an adverse effect on our servers. 

In order to resolve this issue we have introduced usage limits on our API for the following reasons

• Protect the server from overload
• Abuse of the system by the API clients
• Introduce a fair sharing of resources by the API consumers (Avoid starvation of requests by clients)

Rate limiting for HighQ API:

HighQ has decided to introduce per user rate limiting, which is based  on OAuth token per device per user OR in other words per OAuth token rate limiting.

The Collaborate server records the following information to manage rate limit : 

• OAuth key for the client

• Source client or the IP address of each individual device

• “Ratelimit-Start-time” records the time when the API request counter starts on first API request.

• The “Ratelimit-Start-time” is set to new value when the time goes beyond the counter limit, e,g if the API allows 10 requests per minute, after every 1 minute when the new API request comes in from the same client, the “Ratelimit-Start-time” is set to the new time. Say if the first request comes in at 10:20:10 am, only the counter and Total Requests count will keep on increasing until a request comes in at 10:21:13 at that time Reset time will be set to 10:21:13 and counter will be reset to 1.

• If between 10:20:10 am and 10:21:10 am the no of requests exceed 10, then a 429 error will be returned by the API, and the retry header will send a time of 10:21:10 am to the client.
  
  The header is as under

  • X-Ratelimit-Reset  (UTC time in epoch seconds)
     

The Response header is as under

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>
      <summary>{Description of the error}</summary>
</error>

the description of the error strings can be

• The user API call limit has exceeded 
• The Application API call limit has exceeded

• For each API request the response header indicates at what rate limit the API request is, so that the client can optimise their API requests accordingly.
  The header values are as under

  • X-Ratelimit-Limit: the rate limit ceiling for that given request

  • X-Ratelimit-Remaining: the number of requests left for the time window

  • X-Ratelimit-Reset: the remaining window before the rate limit resets in UTC

• The total requests keeps on increasing irrespective of time, to record the overall requests from the client.

The API client should keep consideration of the above three parameters to determine where they are with the API rate limit, and optimise their application based on that. Once the API rate limit has exceeded for a specific API client no more API calls will be served until the rate limit has been reset.  

Note:

The default rate limits are as under

• The token rate limit is 2000 calls in 10 min 
• 8000 calls in 2 min for Application rate limit