API Rate Limits

This article gives you all the information you need to know about TELAIR API Rate Limits.

What is a Rate Limit?

A “rate limit” is a policy that affects the frequency with which an API can be called. They are put in place to protect server infrastructure from being abused or misused. TELAIR employs rate limits to enable consistent load allocation with our platform.

Applying Rate Limits

TELAIR assigns API requests into four different policies where each policy is restricted to a different rate limit. This allows TELAIR to optimize and distribute load across the platform to better secure and protect it. The four policies are described in Table 1 below:

API PolicyRate LimitThrottle Level
Light50 requests/minute60 seconds
Medium40 requests/minute60 seconds
Heavy10 requests/minute60 seconds
Auth5 requests/minute0 seconds

Table 1

Within the above presented limits, your API requests are allowed to send 10 heavy, 40 medium, 50 light and 5 authorization requests per user / per minute. If you exceed these limits, the server returns the ‘429 Too Many Requests’ HTTP error code. It means that the client is throttled by the server due to the high request rate. The retry period (in seconds) after which more requests can be sent, is specified in Retry-After response header.

How best to detect and respond to rate limits

Rate Limits are returned in specific headers in response to each request, unless the request is unlimited. Those headers are:

HeaderDescription
X-Rate-Limit-PolicyAPI category of the given request (Light, Medium, Heavy, Auth)
X-Rate-Limit-LimitCurrent rate limit for the given request
X-Rate-Limit-RemainingThe number of requests left for the time interval (window) of this rate limit
X-Rate-Limit-WindowTime interval in seconds for the given request rate limit

Table 2

These headers are returned in order to enable apps to preemptively respond to circumstances in which their requests may be impacted by a rate limit enforcement.

HTTP/1.1 200 O
K
X-Rate-Limit-Policy: light

X-Rate-Limit-Limit: 1000
X-Rate-Limit-Remaining: 999
X-Rate-Limit-Window: 60
Content-Language: en-US

Content-Type: application/json; charset=UTF-8

{

"meta" : {},
"data: {},

"link" : {}

}

What to do when your requests hit a rate limit?

Consider the following two use cases in which you might hit a rate limit.

1. Simple single-threaded use case

  • If you encounter a HTTP Response Header X-Rate-Limit-Remaining that reaches 0, then wait the number of seconds defined in X-Rate-Limit-Window HTTP Response Header. 
  • If you encounter a HTTP Response Status code of 429, wait the number of seconds defined in the Retry-After HTTP Response header.

If X-Rate-Limit-Remaining is working properly, your app should never encounter a 429 error, which is desirable. In other words, if you build your app to be aware of this HTTP header and to respond accordingly, you can prevent your app from being impacted, or at least alert TELAIR about the issue.

2. Server is overloaded

If you encounter a HTTP Response Header 503, wait a default amount of time and retry once. Then have your app support the following configuration options:

  • Default retry time
  • Max number of retries