Rate Limits

Timekit receives many requests over time. In order to protect the API from a large burst of requests, Timekit utilizes rate limits. If a rate limit is triggered on a production account, your client will receive an HTTP 503 error code from the Timekit API. In addition, test accounts can receive HTTP 429 error codes in the responses. The rate limits are described below.

Production Account Limits

An active production account has a limit of 10 requests per second. Making more than 10 requests per second results in an HTTP 503 error being received. Production accounts allow for “bursting” requests beyond the 10 requests per second limit. To do this, Timekit’s API employs a leaky bucket algorithm, which can be explained through the following analogy:

Every app has access to a bucket of requests. This bucket behaves in the following manner:

  • It has a maximum capacity of 10 requests.

  • It removes and executes 10 requests every second.

  • Any request the app makes is added to this bucket.

  • If you attempt to add a request to an already full bucket, you receive an error.

This way if you decide to exceed the bucket’s request execution rate, you can continue to fill this bucket until the maximum capacity is reached,

Test Account Limits

Test accounts have an additional limit of 3000 requests a day. Making more than 3000 requests a day will result in an HTTP 429 error being received. As soon as the total requests in the last 24 hours are less than 3000, the API will allow for new requests. Daily request capacity cannot be increased.

Although the limits are given, it’s important not to consistently aim to hit these boundaries. These boundaries are strictly the maximum and so you should aim to rarely reach these limits. In order to assist this goal, we have provided a few methods for handling the rate limits.


Handling the Rate Limits

A simple way to handle the rate limits is to build a request handling mechanism. If it receives an HTTP 503 or 429 error, it should wait for a little and retry the request. If it once again receives an error it should wait longer. This exponential backoff helps reduce the request volume whilst also alerting you when you can make requests again.

Caching

One cause of reaching the rate limit is the fact that websites make API calls to Timekit every time they are loaded. This can happen if you decide to add Timekit to the homepage of your website. If this is the exact case, a simple solution would be to move Timekit’s information to a separate page.

Alternatively, the better solution would be to cache GET requests made from Timekit. A lot of the time the information being received between requests doesn’t change. Simply caching the information, even every 10 minutes will result in a drastic decrease in requests made to the server. Furthermore, you can choose to add a force update button along with a timer stating when the last update was made, further helping to keep the information up to date.

Spreading out the requests

Another cause of reaching the limit is a large number of requests during the busy website traffic hours. If you face this issue, you can create a queue of requests and spread them out over time. Base this on the above-mentioned limits and you should be able to manage the rate limits even during high traffic hours.

Did this answer your question?