API Rate Limits are in place to allow GatherContent to provide an efficient and high-performing API. We measure the amount of requests each user sends to the API in order to throttle if they surpass the amount allowed.

You should design your application with these limits in mind and implement a graceful handling strategy.

The returned HTTP headers of any API request show your current rate limit status:

curl -i https://api.gathercontent.com/projects/1/items
HTTP/1.1 200 OK
Date: Mon, 01 Jan 2020 09:00:00 GMT
Status: 200 OK
X-RateLimit-Limit: 25
X-RateLimit-Remaining: 22

Once the rate limit has been reached we will respond with '429 Too Many Requests':

curl -i https://api.gathercontent.com/projects/1/items
HTTP/1.1 429 Too Many Requests
Date: Mon, 01 Jan 2020 09:00:00 GMT
Status: 429 Too Many Requests
X-RateLimit-Limit: 25
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1577869230
Rety-After: 30
{
  "error": "Too Many Attempts.",
  "code": 429
}

Header	Description
X-RateLimit-Limit	The maximum number of requests you are allowed to make per minute.
X-RateLimit-Remaining	The number of requests left in the current rate limit window.
X-RateLimit-Reset	The Unix timestamp at which the rate limiter will be reset to the maximum limit.
Retry-After	The number of seconds until the rate limiter will be reset to the maximum limit.

How many request can I make?

Api request are currently limited to 250 requests every 15 seconds

When does the amount of requests reset?

If you hit your api limits within the 15 second window then you will be throttled until the end of that 15 second window.

Handling limiting gracefully

A simple technique for integrations to handle rate limiting is to look for 429 status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume if necessary.