Improved 429 Response Headers – April 2nd, 2018

Along with our recent rate limit updates, we at Clover are introducing improved 429 response headers based on your feedback.

With these improvements, you can better understand:

  • The type of rate limit that your app has reached
  • Your app’s current rate limit value
  • The duration you are required to wait until your app can make additional requests

This information is found in two key-value fields: retry-after and X-RateLimit-{type}


The retry-after field specifies the number of seconds you are required to wait before your app can make any additional requests. If your app makes additional requests before this time expires, the waiting period increases.

Example response:

retry-after: 21


There are four variants of the X-RateLimit-{type} field, depending on the type of rate limit that has been reached. In addition to specifying the type of rate limit reached, this key informs you of your app’s current rate limit value.. You should always keep your requests under the rate limit value.

Example response:

X-RateLimit-tokenLimit: 16


The following table shows the four variants of this field and their descriptions:

Header field Rate limit Default value
X-RateLimit-tokenLimit Per token 16
X-RateLimit-crossTokenLimit Per app 50
X-RateLimit-tokenConcurrentLimit Per token concurrently 5
X-RateLimit-crossTokenConcurrentLimit Per app concurrently 10