Handle Rate Limits Without Losing Requests

import { setTimeout as delay } from 'node:timers/promises';

export async function getWithRateLimit(url, {
  headers = {},
  maxAttempts = 3,
  maxWaitMs = 30_000,
  requestTimeoutMs = 10_000,
  fetchImpl = fetch,
  sleep = delay,
  now = Date.now,
  random = Math.random,
} = {}) {
  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 10) {
    throw new RangeError('maxAttempts must be an integer between 1 and 10');
  }
  if (!Number.isFinite(maxWaitMs) || maxWaitMs < 0 || maxWaitMs > 300_000 ||
      !Number.isInteger(requestTimeoutMs) || requestTimeoutMs < 1 || requestTimeoutMs > 300_000) {
    throw new RangeError('Use a wait budget of 0–300000 ms and a timeout of 1–300000 ms');
  }
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetchImpl(url, {
      method: 'GET', headers, signal: AbortSignal.timeout(requestTimeoutMs),
    });
    if (response.ok) return response;
    const error = new Error(`GET failed with HTTP ${response.status}`);
    error.status = response.status;
    if (response.status !== 429 || attempt === maxAttempts - 1) {
      await response.body?.cancel();
      throw error;
    }
    const retryAfter = response.headers.get('retry-after');
    let waitMs;
    if (retryAfter !== null && /^\d+(?:\.\d+)?$/.test(retryAfter.trim())) {
      waitMs = Math.ceil(Number(retryAfter) * 1000);
    } else if (retryAfter !== null && !/^[-+]?\d/.test(retryAfter.trim()) &&
               Number.isFinite(Date.parse(retryAfter))) {
      waitMs = Math.max(0, Date.parse(retryAfter) - now());
    } else {
      waitMs = Math.ceil(500 * 2 ** attempt + 250 * random());
    }
    await response.body?.cancel();
    if (!Number.isFinite(waitMs) || waitMs > maxWaitMs) {
      throw new Error('Retry-After exceeds the wait budget; defer this read');
    }
    await sleep(waitMs);
  }
}

import { getWithRateLimit } from './rate-limit.mjs';

const key = process.env.RESPONSECX_API_KEY;
if (!key) throw new Error('Set RESPONSECX_API_KEY with agents:read scope');
const response = await getWithRateLimit('https://response.stateset.com/api/v1/agents', {
  headers: { Authorization: `Bearer ${key}` },
});
const body = await response.json();
if (!Array.isArray(body.data)) throw new Error('Expected an agent list');
console.log(`Read ${body.data.length} agents`);

node read-agents.mjs

npm run test:docs