Handle rate limits and back off correctly

Read the headers

Every response — success or 429 — carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. When Remaining is low, pace yourself before you hit the wall rather than waiting for the 429. This works on both the public 60/60s ring and the partner token bucket.

Back off with jitter

let delay = base;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
  const res = await call();
  if (res.status !== 429 && res.status < 500) return res;
  const reset = Number(res.headers.get('RateLimit-Reset')) || delay;
  await sleep(reset * 1000 + Math.random() * 250);  // jitter
  delay = Math.min(delay * 2, maxDelay);             // exponential, capped
}

Jitter stops many clients retrying in lockstep; the cap stops the delay growing without bound.

Know when to stop

Cap total attempts and then surface a clear failure — an infinite retry loop is worse than a clean error. Never retry a 4xx that is not 429; those are your bug, not a transient condition. On writes, keep the idempotency key constant across retries.