Fundamentals
Rate limits
Two limiting layers, the X-RateLimit headers, and what to do after a 429.
Rate limiting has two layers protecting different things.
Layer 1 — IP pre-limit
Runs before the key is even verified: 120 requests per 10 seconds per IP. Its purpose is to keep junk blsk_ prefixes from ever reaching the database.
A legitimate integration should not hit this; if you do, you have probably opened too much parallelism.
Layer 2 — Per-key limit
Runs after verification. 300 requests per minute by default; raisable per key (via support).
Every response reports the state:
HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 41| Header | Meaning |
|---|---|
X-RateLimit-Limit | Allowance per window |
X-RateLimit-Remaining | Left in this window |
X-RateLimit-Reset | Seconds until the window resets |
When you hit it
{ "type": "error.list",
"errors": [{ "code": "rate_limit_exceeded", "message": "Too many requests." }] }The response is 429 and carries Retry-After.
Wait out Retry-After. Retrying at a fixed interval keeps the window permanently full and your integration never makes progress. The correct behaviour is: wait Retry-After, then continue with exponential backoff.
async function request(url: string, init: RequestInit, attempt = 0): Promise<Response> {
const r = await fetch(url, init);
if (r.status !== 429 || attempt >= 5) return r;
const wait = Number(r.headers.get("retry-after") ?? 1) * 1000;
// Jitter is REQUIRED: if 50 clients hit the limit at once and all come back at
// the same moment, the window refills instantly and none of them progresses.
const jitter = Math.random() * 250;
await new Promise((done) => setTimeout(done, wait + jitter + attempt * 500));
return request(url, init, attempt + 1);
}If Redis goes down
The limiting infrastructure does not fail fully open: it falls back to a conservative in-process window (30 requests per 10 seconds) and a global concurrency cap. An infrastructure failure never leaves the API unprotected — but it runs in a narrower band than usual. You are more likely to see 429s during such a period; the same backoff logic is the right response.
Writing a bulk job
- Cap your parallelism. 300/min is 5 requests per second; 50 parallel workers burn the limit in the first second.
- Watch
X-RateLimit-Remaining. Slow yourself as it drops; hitting the limit and backing off costs more than never hitting it. - Use Idempotency-Key on writes. A POST resent during backoff creates a second record without one.