WHIZZHIRE
Docs · Reference · Rate limits

Rate limits.

Limits are per API key, counted in a fixed 60-second window. The default budget is 60 requests per minute per key.

How the window works#

The first request on a key opens a 60-second window; every request in that window counts against the key's budget. When the window expires, the count resets in full — there is no gradual token refill. Exceeding the budget returns 429 until the reset.

The limit is stored per key (rate_limit_rpm), so different keys — say, a high-volume backfill key and a low-volume production key — can have different budgets. Need more than 60? Ask at support@whizztech.ai.

Response headers#

Every authenticated response reports where you stand:

Rate-limit headers
HTTP/1.1 200 OK
Content-Type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 57
x-ratelimit-reset: 1751795160
FieldTypeDescription
x-ratelimit-limitintegerThe key's budget per 60-second window.
x-ratelimit-remainingintegerRequests left in the current window.
x-ratelimit-resetunix secondsWhen the current window resets and the budget refills.
retry-aftersecondsOnly on 429: how long to wait before retrying (minimum 1).

The 429 body uses the standard error envelope with code rate_limit_exceeded.

Best practices#

  • Honor retry-after. It is computed from the actual window reset, so waiting exactly that long always succeeds. Minimal client:
Node — honor retry-after
async function withRetry(fn, maxRetries = 2) {
  for (let attempt = 0; ; attempt++) {
    const res = await fn();
    if (res.status !== 429 || attempt >= maxRetries) return res;
    const retryAfter = Number(res.headers.get("retry-after") ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
}
  • Poll with backoff, not a tight loop. A 1-second poll on 10 concurrent jobs is 600 requests/min — 10x the default budget. The backoff pattern in Jobs (1.5s growing to 10s) keeps 10 jobs under 10% of it.
  • Prefer webhooks for completion. One job.succeeded delivery replaces an entire polling session — see Webhooks.
  • Use Idempotency-Keys on creation. A retry after a timeout then can never double-charge you, which makes aggressive retry policies safe.
  • Split keys by workload. Give batch backfills their own key so a burst there can never starve your production traffic.
NextSDK→