Rate limits

The Gatsby API allows each caller 90 requests per minute, with bursts of up to 20 requests at once. Requests over the limit get a 429 Too Many Requests response and a Retry-After header telling you how many seconds to wait.

The limit protects the API from runaway scripts so it stays fast for everyone. Most integrations never reach it. If you update many contacts at once, use Update many persons to send up to 100 updates in one request.

How the limit works

Think of the limit as a bucket of 20 tokens. Each request takes one token, and the bucket refills at 1.5 tokens per second (90 per minute). You can send 20 requests back to back, then keep going at about 3 every 2 seconds. When the bucket is empty, requests get a 429 until a token comes back.

Requests are counted per caller:

Name
API key
Description
When you authenticate with an API key, every request made with that key shares one limit.
Name
Access token
Description
When you authenticate with an access token, every request made with that token shares one limit. The organizationSlug header does not change which limit you use.

Every request counts as one against this limit, whatever it does.

429 response

{
  "message": "Too Many Requests. Retry after 1 seconds."
}

Bulk updates

Update many persons (PUT /persons) has a second limit of its own: 20 requests per minute, with bursts of up to 5. One request can update 100 contacts, so this still lets you update up to 2,000 contacts a minute.

A bulk request counts against both limits. Reaching the bulk limit does not affect your other requests.

Response headers

Name
X-RateLimit-Limit
Type
integer
Description
The size of your bucket: the most requests you can send back to back (20, or 5 on PUT /persons).
Name
X-RateLimit-Remaining
Type
integer
Description
The number of requests you can send right now before you have to slow down. On PUT /persons both headers describe whichever limit is closer to running out.
Name
Retry-After
Type
integer
Description
Sent only with a 429. The number of seconds to wait before retrying.

Handling a 429

When you get a 429, wait for the number of seconds in Retry-After, then send the same request again:

import time
import requests

def request_with_retry(method, url, **kwargs):
    while True:
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "1")))

If a job regularly reaches the limit, spread its requests out over time or batch them. For contact updates, PUT /persons does the work of 100 single updates in one request.