RingCentral API rate limits

What is a rate limit?

A "rate limit" is a policy that affects the frequency an API can be called. They are put in place to protect server infrastructure from abuse or misuse. RingCentral employs rate limits to enable consistent load allocation across our platform.

How are rate limits calculated?

Every RingCentral API is assigned to a different "API Group" which determines the default rate limit that an application will be subject to when called that API. This allows each API to be assigned a rate limit based upon the most common usage patterns associated with that API. This also allows RingCentral to better manage and distribute potential load across the platform to better secure and protect it.

The four basic rate limit groups are below. Please note that the rate limits and throttle intervals are provided as an example only, as they can be customized and therefore may vary from app to app.

Rate limits can be customized and vary in the following ways: * Rate limits can be assigned to different time intervals, e.g. n calls per minute, per hour, per 5 minutes, etc. * API Groups may also support multiple limits per group, based upon the unique needs and the APIs called by an app.

How do I determine the rate limit associated with an API?

Every API endpoint is assigned to a different "API group." The API group for every API is disclosed on its corresponding page in the API Reference under the heading of "API Group."

What are the specific rate limits associated with my app?

In addition to our default limits, RingCentral administrators have the ability to modify rate limits on an app-by-app basis in order to better service the unique needs of our developers. You can view your app's specific rate limits by logging into the Developer Console, loading your app's dashboard, and clicking "Rate Limits." That will show you a page similar to the following:

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

How do I detect and respond to my app being throttled?

When an app exceeds its rate limit, the platform will begin to throttle the app, prohibiting more API calls from being made. When this happens, any call to the API will result in a failure, with an HTTP status code of 429 being returned.

In addition, other HTTP headers are returned to signal to the developer what their limits are, and when they will be reset. This allows developers to code defensively around these potential failure conditions and implement retry logic as needed.

There are a few other instances in which your application might also receive a 429 error code, including:

• Account-level limit set
• Any custom rate limit provided by API service

In these circumstances, the error message you receive may not communicate what your specific and custom rate limit might be. Therefore we recommend consulting the Developer Console to see the actual rate limits configured for your application.

Rate limit response headers

Rate limits are communicated via specific HTTP headers that should be returned in a response for each request (although may not be present in 100% of responses), unless the request is unlimited. Those headers are:

Example

Let us consider the example of request retrieving account information. Rate Limits headers are returned in response alongside with HTTP status code.

HTTP/1.1 200 OK
X-Rate-Limit-Group: 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

{
  "uri" : "https.../restapi/v1.0/account/1696121004",
  "id" : 1696121004,
  "serviceInfo" : { /* snip */ },
  "operator" : { /* snip */ }, 
  "mainNumber" : "+18775550010",
  "status" : "Confirmed",
  "setupWizardState" : "Completed"
}

What to do when your app hits a rate limit

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

Simple single-threaded use case, e.g. downloading files serially

• 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 personnel about the issue.

Server is overloaded

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

• Default retry time
• Max number of retries

The Amazon Web Services SDK implements a feature called exponential backoff, excerpted below:

In addition to simple retries, each AWS SDK implements exponential backoff algorithm for better flow control. The idea behind exponential backoff is to use progressively longer waits between retries for consecutive error responses. You should implement a maximum delay interval, as well as a maximum number of retries. The maximum delay interval and maximum number of retries are not necessarily fixed values, and should be set based on the operation being performed, as well as other local factors, such as network latency.

Most exponential backoff algorithms use jitter (randomized delay) to prevent successive collisions. Because you aren't trying to avoid such collisions in these cases, you don't need to use this random number. However, if you use concurrent clients, jitter can help your requests succeed faster. For more information, see the blog post for Exponential Backoff and Jitter.