Concepts

Rate limits

120 requests per minute per key, the headers, and how to back off.

The limit#

Each key may make 120 requests per minute (your server operator can change this). The minute is a calendar minute (UTC); the count starts again at the next full minute. Separate integrations with separate keys have separate limits.

Every answer tells you where you stand:

HTTP

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87

Above the limit Quilo answers:

HTTP

HTTP/1.1 429 Too Many Requests
Retry-After: 23

JSON

{ "error": { "type": "rate_limited", "message": "Too many requests for this key. Wait until the next minute (see Retry-After).", "request_id": "req_…" } }

Back off and retry (Python)#

Python

import os, time, random, requests

def quilo(method, path, **kw):
    url = f"{os.environ['QUILO_URL']}/api/v1/{path}"
    headers = {"Authorization": f"Bearer {os.environ['QUILO_API_KEY']}", **kw.pop("headers", {})}
    for attempt in range(6):
        r = requests.request(method, url, headers=headers, timeout=30, **kw)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        if r.status_code >= 500:
            time.sleep(min(2 ** attempt, 30) + random.random())
            continue
        return r
    r.raise_for_status()
    return r

Staying under the limit#

Use limit=200 when listing, not many small pages.
Sync changes with updated_since / created_since instead of fetching everything.
Cache data that rarely changes, such as brands.
Spread large imports over time; 120 per minute is 7,200 records an hour.