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
HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 41
HeaderMeaning
X-RateLimit-LimitAllowance per window
X-RateLimit-RemainingLeft in this window
X-RateLimit-ResetSeconds until the window resets

When you hit it

json
{ "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.

ts
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.