429 Too Many Requests when generating PDFs in bulk

What is actually happening

Unbounded concurrency. Mapping over a list with a promise per item starts every request at once, so a thousand payslips become a thousand simultaneous requests regardless of what any limit allows.

Confirming it is this and not something that looks like it

Count how many requests are in flight at the peak. If it equals the size of your input list, you have no concurrency control at all.

The fix

Bound concurrency, and retry the ones that are limited with exponential backoff and jitter. For a run that is genuinely large, use the batch endpoint rather than managing concurrency yourself.

async function mapWithLimit(items, limit, fn) {
  const results = new Array(items.length);
  let cursor = 0;

  async function worker() {
    while (cursor < items.length) {
      const i = cursor++;
      results[i] = await withRetry(() => fn(items[i]));
    }
  }

  await Promise.all(Array.from({ length: limit }, worker));
  return results;
}

async function withRetry(fn, attempts = 5) {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status !== 429 || attempt >= attempts) throw err;
      // Exponential, with jitter so a batch does not retry in lockstep.
      const wait = 2 ** attempt * 250 + Math.random() * 250;
      await new Promise((r) => setTimeout(r, wait));
    }
  }
}

If that was not it

These produce the same symptom often enough to be worth ruling out before assuming the fix above did not work.

• Promise.all over the whole list, which is the unbounded case in its most common form
• Retries with no jitter, which resynchronise the burst you were trying to spread
• A Retry-After header, which tells you exactly how long to wait
• A queue worker whose concurrency was raised without anyone thinking about the downstream

Frequently asked

Related failures

Problems people arrive at from the same starting point, or mistake for this one.