waitForRun and 429 or 503 on a status read: it keeps polling

When a status read returns 429 or a 5xx, the run itself has not failed, and waitForRun does not treat it that way. The SDK tolerates 6 consecutive transient read failures by default, backing off and polling again, because losing the handle to a live run is far more expensive than waiting another second. Raise or lower the tolerance with maxTransientFailures and log each one with onTransientError.

Sources: Waiting for runs and jobs and Errors and spend, read 2026-10-02.

Why is a failed read not a failed run?

The Formats docs are explicit: a 429 or 503 in a poll loop is transient. The read budget is spent, or Sume had a short upstream outage, but the run keeps executing and its spend keeps accruing. Abandoning the loop does not stop it. Bulk queues follow the same rule: a 429 or 503 while polling a queue means the queue is still draining.

How do I wire the options?

Pass onTransientError so repeated blips show up in your logs instead of vanishing. The docs do not name the error thrown once the limit is passed, so catch any error around the wait. The run is still alive, so record the id and resume from result_url or start a fresh wait.

import { createSumeClient, waitForRun } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });

const run = await waitForRun(runId, {
  client,
  family: "format",
  timeout: 15 * 60_000,
  pollInterval: 2_000,
  maxTransientFailures: 6,
  onTransientError: (err) => console.warn("transient read failure", err),
});
console.log(run.status);

Why does the poll not stay in lockstep?

Polls are jittered. Reads have their own budget, but several clients started together would otherwise stay in phase and hit that ceiling as a group. The deadline is also checked before sleeping, not after, so a caller who asks for a 5-second timeout hears about it in 5 seconds rather than 5 seconds plus one poll interval.

The failure counter counts consecutive failures, so one good read resets the picture. A long outage that outlasts the tolerance ends the wait, not the run.

What should I do when the wait gives up?

Treat that as a handoff, not a failure. Persist runId, mark it pending, and have a scheduled job resume it. Better still, ask for a run webhook so you are told on completion, and keep this loop as the backup.

Do not start a second paid run for the same intent. If you must retry a create, reuse the same Idempotency-Key so you get the original receipt back.