Rate limits

Per-key request limits, the RateLimit headers on every response, and how to back off from 429s.

Each API key may make 300 requests per minute by default (your account may have a different limit). The limit is a token bucket: it holds a full minute of requests and refills continuously, so short bursts up to the limit are fine.

#Headers

Every authenticated response tells you where you stand:

RateLimit-Limit: 300
RateLimit-Remaining: 287
RateLimit-Reset: 3
RateLimit-Policy: "per-minute";q=300;w=60
RateLimit: "per-minute";r=287;t=3

#When you hit the limit

The API answers 429 with code: rate_limited and a Retry-After header (seconds):

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

Wait at least Retry-After seconds, then retry the same request (same Idempotency-Key). Add exponential backoff with jitter if you keep getting 429s.

async function withRateLimit(doRequest, attempts = 5) {
  for (let i = 1; ; i++) {
    const res = await doRequest();
    if (res.status !== 429 || i >= attempts) return res;
    const wait = Number(res.headers.get("retry-after")) || 2 ** i;
    await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 250));
  }
}

import random, time

def with_rate_limit(do_request, attempts=5):
    for i in range(1, attempts + 1):
        res = do_request()
        if res.status_code != 429 or i == attempts:
            return res
        wait = float(res.headers.get("Retry-After") or 2 ** i)
        time.sleep(wait + random.random() * 0.25)

#Staying under the limit

• Use webhooks instead of polling for order status changes.
• Page with limit=100 to fetch lists in fewer requests.
• Cache the catalog — it changes rarely; listen to catalog.price_changed for price updates.
• Spread bulk jobs (product imports, backfills) over time, or use separate keys per integration — limits are per key.
• Need more? Contact support@swaglists.com with your expected volume.