Understanding REST Headers and Parameters for RingCentral APIs and avoiding HTTP 429 throttling error

  • 1
  • Idea
  • Updated 2 years ago
  • (Edited)
Headers are the true metadata of an API transaction request. In general, the header fields start on the second line of a message, after the request line. All fields are name-value pairs (separated by a colon), and terminated by a new line. Long lines can be folded onto multiple lines; continuation lines start with either a blank space or tab character. The end of the header fields is indicated by an empty line, which is then followed by the body of the message.

Custom headers should only be used for things that do not involve the name of the resource (should be passed in the URL), the state of the resource (should be passed in the body), or parameters directly affecting the resource (should be passed as URL parameters).

Lets see how the custom header look for RingCentral API response.


API :  /oauth/token 





Server: nginx/1.8.0
Date: Fri, 25 Mar 2016 21:43:18 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 1051
Connection: keep-alive
RCRequestId: 9668da24-f2d2-11e5-a55a-005056bbcd2d
RoutingKey: SJC11P01PAS02
X-LoadMetric: 6
Pragma: no-cache
Cache-Control: no-store
X-Rate-Limit-Window: 60
X-Rate-Limit-Group: auth
X-Rate-Limit-Remaining: 4
X-Rate-Limit-Limit: 5
Content-Language: en


API : /call-log

Server: nginx/1.8.0
Date: Fri, 25 Mar 2016 22:18:00 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 4146
Connection: keep-alive
RCRequestId: 6f9471f6-f2d7-11e5-a381-005056bbcd2d
RoutingKey: SJC11P01PAS02
X-LoadMetric: 6
X-Rate-Limit-Group: medium
X-Rate-Limit-Limit: 40
X-Rate-Limit-Remaining: 39
X-Rate-Limit-Window: 60
Content-Language: en-US



When you hit 429 throttling error the header looks something like this:
Server: nginx/1.8.0
Date: Fri, 25 Mar 2016 22:09:34 GMT
Content-Type: application/json;charset=UTF-8
Content-Length: 168
Connection: keep-alive
RCRequestId: 41f7b75e-f2d6-11e5-b962-005056bbcd2d
RoutingKey: SJC11P01PAS02
X-LoadMetric: 6
Retry-After: 60
X-Rate-Limit-Window: 60
X-Rate-Limit-Group: auth
X-Rate-Limit-Remaining: 1
X-Rate-Limit-Limit: 5
X-ERROR-ID: 4dc5769e-fd1b-40a4-991c-b532dcaa2343
Content-Language: en

Usage plan determines how many requests could be sent per minute(RPM) for a particular api.
For more information on USAGE PLANS and RPM LIMITS please view this link:
https://developer.ringcentral.com/api-docs/latest/index.html#!#UsagePlanDetails.html

Custom header explains few things here: (varies based on the usage plan)

X-Rate-Limit-Window: 60 (seconds)
Rate-limit is the time window for calcualting number of requests per minute(RPM)

 X-Rate-Limit-Group: auth , medium, heavy, light
Rate-Limit-Group is the usage group to which the api belongs to
Here, /oauth/token belongs to auth group

 X-Rate-Limit-Remaining:
Rate-Limit-Remaining is number of requests that could be sent in that minute

  X-Rate-Limit-Limit:
Rate-Limit-Limit is maximum number of requests allowed in a minute.



When you hit a throttling limit, you are actually exceeding X-Rate-Limit-Limit  and your X-Rate-Limit-Remaining will be 1. This is when you  need to stop for the number of seconds mentioned in the Retry-After field. 

These suggestions should come in handy when you are developing your applications to avoid throttling limits and running your application error-free.

Please read this article on how to avoid hitting 429 throttling error. https://devcommunity.ringcentral.com/ringcentraldev/topics/429-too-many-requests-error



HAPPY CODING!!!!
Photo of VB

VB, Official Rep

  • 1,310 Points 1k badge 2x thumb

Posted 2 years ago

  • 1

Be the first to post a reply!