Improved 429 Response Headers for Rate Limits

Based on developer feedback, we introduced additional fields to Clover’s 429 response headers. The additional fields will help you better understand and respond when you reach Clover’s rate limits.

With these improvements, the rate limit headers will include:

• 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: X-RateLimit-{type} and retry-after.

New 429 response header fields

X-RateLimit-{type}

We now provide 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, the field’s value informs you of your app’s current rate limit. Note that you should always keep your number of requests under the rate limit value.

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

Example header field:

X-RateLimit-tokenLimit: 16

retry-after

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 header field:

retry-after: 21

Using the new response headers

When you receive a 429 Too Many Requests response, your app must respond appropriately or risk getting your service severely disrupted. After identifying which rate limit has been reached, make sure your app logs this data and modifies its behavior appropriately.

Concurrent rate limits

Receiving a response with the header X-RateLimit-tokenConcurrentLimit or X-RateLimit-crossTokenConcurrentLimit indicates that your app is making too many concurrent requests. A request is considered concurrent if there’s another in-progress request that has not returned a response.

To avoid hitting this rate limit:

• Limit the number of simultaneous threads making requests to under your concurrent rate limits, which is found in the X-RateLimit-tokenConcurrentLimit and X-RateLimit-crossTokenConcurrentLimit fields.
• Use filters like modifiedTime or createdTime to narrow your requests and make them more efficient.
• Do not retry the same request until you receive a response.
• Enable logging in your app to help you debug.

Request rate limits

Receiving a response with X-RateLimit-tokenLimit or X-crossTokenLimit indicates that your app is reaching our request rate limits, signaling too many requests per second.

If you receive a 429 Too Many Requests response, pause making any additional requests for the number of seconds specified in the retry-again field (as shown in the sample code below). Also, make sure requests across all threads are paused.

To avoid hitting this rate limit:

• Keep the number of requests per token and per app under your rate limit values found in the X-RateLimit-tokenLimit and X-crossTokenLimit fields.
• Spread out the requests over a longer period of time.
• Use expansions to consolidate requests.
• Use the Export API to get bulk payment and order data.

The following Python code demonstrates how to utilize the retry-again field to pause your requests:

Here are the logs of receiving a 429 Too Many Requests response while running this code. Note that after receiving this response, the retry request is paused for 22 seconds, as specified in the retry-again field.

https://apisandbox.dev.clover.com/v3/merchants/EWQCCKANA1WZ0/orders
2018-04-05 15:10:30,811 - INFO - Starting new HTTPS connection (1): api.clover.com
2018-04-05 15:10:31,016 - DEBUG - "GET /v3/merchants/EZQWCVKNA2WZ0/orders HTTP/1.1" 429 35
2018-04-05 15:10:31,020 - ERROR - {"message":"429 Too Many Requests"}
{'content-length': '35', 'expires': 'Tue, 17 Sep 1991 10:00:00 PST', 'retry-after': '22', 'pragma': 'no-cache', 'cache-control': 'no-cache, no-store, must-revalidate', 'X-Frame-Options': 'SAMEORIGIN', 'content-type': 'application/json; charset=utf-8', 'X-RateLimit-tokenLimit': '16'}
2018-04-05 15:10:53,239 - INFO - Attempt completed
https://apisandbox.dev.clover.com/v3/merchants/EWQCCKANA1WZ0/orders
2018-04-05 15:10:53,243 - INFO - Starting new HTTPS connection (1): api.clover.com
2018-04-05 15:10:53,453 - DEBUG - "GET /v3/merchants/EWQCCKANA1WZ0/orders HTTP/1.1" 200 None
2018-04-05 15:10:53,457 - INFO - 200 https://apisandbox.dev.clover.com/v3/merchants/EWQCCKANA1WZ0/orders

As a Clover developer, make sure to update your app’s retry logic to utilize the new headers. Adhering to the other guidelines mentioned above will help you avoid hitting our rate limits.

If you have additional questions on the new response headers, post your questions on community.clover.com.