# Rate limits

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

Source: https://swaglists.com/docs/rate-limits

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:

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

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | Requests per minute for this key. |
| `RateLimit-Remaining` | Requests left right now. |
| `RateLimit-Reset` | Seconds until the bucket is full again. |
| `RateLimit-Policy`, `RateLimit` | The same information in the IETF structured-header format. |

## When you hit the limit

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

```http
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.

```js title="Node.js"
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));
  }
}
```
```python title="Python"
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.