Does the Sume SDK retry POST? Only with an Idempotency-Key

createSumeClient retries 408, 429, 5xx and transport failures up to 2 times by default, with exponential backoff and jitter, honoring retry-after. But a POST is retried only when it carries an Idempotency-Key. Without one, a replay would start and bill a second run, so the client sends the request once and surfaces the failure.

Details are from Waiting for runs and jobs and Jobs and results, read 2026-10-02.

What are the defaults?

Two layers handle transient trouble, both on by default.

Who generates the key?

subscribeFormatRun generates a UUID key for you unless you pass your own idempotencyKey, or null to send none. A replay of a finished run returns immediately. For the generated job operations, such as generateVideoV1, you pass the key yourself in the idempotency-key header, as the job example in the docs does.

For a stable key, derive it from your own business event, such as an order id plus a version, not from a clock. A random key per attempt defeats the point, because every retry then looks like a new request.

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

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

const { data, error } = await generateVideoV1({
  client,
  headers: { "idempotency-key": "order-8823-hero-v1" },
  body: { prompt: "Slow push-in on a ceramic mug", mode: "async" },
});
if (error) throw new Error(JSON.stringify(error));
console.log(data!.data.request_id);

What does a replay return?

Retrying a submit with the same Idempotency-Key returns the original job instead of billing a second one. The docs say to reuse the key only for the same operation and payload. A different body under a used key is a 409 idempotency_conflict, and a request still in flight under the same key is 409 idempotency_key_in_use, which is retryable after about a second.

A failed create releases its key, but a run that failed after it started keeps the key bound to its receipt, so retry a failed run with a new key.

What should I check when a POST seems to fail once?

If a call timed out client-side, do not resubmit with a new key. The job may exist and be billing. Resend the same request with the same key, or look the job up by id if you stored it.

• Always send a key on paid creates, so the client can retry safely.
• Store the job id from the first response, since every mode returns one.
• On 429, wait retry-after; on queue_full, wait for a job to finish.
• Do not turn maxRetries up to hide an outage; the loop does not cancel anything.