BullMQ retry: exponential backoff for paid API jobs

To retry a BullMQ job, add it with attempts greater than 1 and a backoff such as { type: 'exponential', delay: 1000 }: when the processor throws, BullMQ retries it after 2^(attempts − 1) × delay milliseconds, optionally with jitter, and without a backoff it retries at once. For a job that calls a paid API, build the Idempotency-Key from the job, so every attempt replays the same run, and throw UnrecoverableError on errors a retry can't fix.

BullMQ facts come from its Retrying failing jobs guide and the other BullMQ pages under Sources; Sume facts come from Create a run and Errors and spend. All were read on 2026-09-28. Sume has no BullMQ package: the worker makes one plain HTTPS call. For retrying a single request inside one process instead of the whole job, see Axios retry: retry a POST safely with an idempotency key.

How do I set attempts and backoff?

Pass them when you add the job, or once in the queue's defaultJobOptions. A job fails when its processor throws, and attempts counts the first try: attempts: 3 means at most 2 retries.

import { Queue } from "bullmq";

const queue = new Queue("videos", { connection });
await queue.add(
  "promo",
  { orderId: "1042" },
  {
    jobId: "order-1042-promo", // a second add is ignored while this id is in the queue
    attempts: 5,
    backoff: { type: "exponential", delay: 1000, jitter: 0.5 },
  },
);

How do I make a retried job safe to pay for?

Give the job a custom jobId from your own record. BullMQ ignores a second add with an id that is still in the queue, and the id follows the job through every state, so a key built from it is the same on every attempt, and Sume answers a repeat with 200, the original receipt and idempotency_hit: true instead of a second charge. Then let Sume's error envelope decide: retryable says whether resending the same request can succeed. The docs say to retry a 503 later with the same key, and a 429 carries retry-after in seconds, which BullMQ's manual rate limit, queue.rateLimit() in milliseconds, can honor for the whole queue.

import { Worker, RateLimitError, UnrecoverableError } from "bullmq";

new Worker("videos", async (job) => {
  const res = await fetch("https://api.sume.com/v1/formats/acme/product-promo/runs", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SUME_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `${job.id}-v1`, // same on every attempt
    },
    body: JSON.stringify({
      input: { order_id: job.data.orderId },
      communication: { webhook_url: "https://example.com/hooks/sume" },
    }),
  });
  const body = await res.json();
  if (res.ok) return body.data.id; // 202: new run, 200: replay
  if (res.status === 429) {
    await queue.rateLimit(Number(res.headers.get("retry-after")) * 1000); // ms
    throw new RateLimitError(); // back to waiting, not a failed attempt
  }
  if (body.error.retryable || res.status === 503) throw new Error(body.error.code);
  throw new UnrecoverableError(`${res.status} ${body.error.code}`);
}, { connection, limiter: { max: 1, duration: 500 } });

Which errors should stop retrying?

Most 4xx answers. A 4xx at create means nothing ran and nothing was charged, so the worker throws UnrecoverableError and the job fails at once instead of spending its attempts. Each Sume error carries a next_action (fix_input, authenticate, add_funds, retry_later, …) that says which case it is in; Axios retry: retry a POST safely lists the codes a retry can't fix, from 402 insufficient_credits to a 502 that is really your input.

The answers Sume marks retryable, such as 409 idempotency_key_in_use while the first attempt is still in flight, and a 503 become plain thrown errors, so they get the job's backoff. A 429 is different: a job rate limited with RateLimitError doesn't use up attempts, because BullMQ doesn't count rate limiting as a real error. To cap it anyway, BullMQ's docs check job.attemptsStarted against job.opts.attempts and throw UnrecoverableError.

What if the run fails after the job succeeded?

Then a BullMQ retry can't help: the old key is bound to the failed receipt, so the same key only replays the failure. Start a new job with a new jobId, such as order-1042-promo-2, so its key is new too. Don't make the processor wait for the video either: long-form video is 15 to 30 minutes of work, and a worker that stops waiting doesn't stop the run or its spend. Return the run id and let Sume POST one signed format.run.terminal receipt to communication.webhook_url when the run completes or fails.