Sume SDK idempotencyKey: null sends no key, so POST retries stop

subscribeFormatRun in @sume-com/sdk sets an Idempotency-Key header for you. If you pass idempotencyKey: null, it sends no header at all, and that changes how the client treats a failed create call: the SDK retries a POST only when an Idempotency-Key is present. This page shows the three settings side by side and when null is the wrong choice.

The retry rule lives in createSumeClient. By default it makes up to two retries (maxRetries: 2) on 408, 429, 5xx and transport failures, honors retry-after (capped at 60 seconds) and adds roughly 20% jitter. GETs retry freely. A POST retries only with a key, because repeating a POST without one could start a second paid run.

The three settings

The option is documented in the SDK guide and the runs reference. Omit it and the SDK generates a UUID per call. Pass a string and you control replay across process restarts. Pass null and you opt out.

Code

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

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });
const path = { handle: "acme", slug: "product-promo" };
const body = { input: { product_url: "https://shop.example.com/p/8823" } };

// Default: the SDK mints a UUID key, so a 429 or 5xx on the create is retried.
const retried = await subscribeFormatRun({ client, path, body });

// null: no Idempotency-Key header, so the create POST is sent once, never retried.
const once = await subscribeFormatRun({ client, path, body, idempotencyKey: null });

// Your own key: restart the process and the same key replays the same run.
const stable = await subscribeFormatRun({
  client,
  path,
  body,
  idempotencyKey: "order-8823-promo-v1",
});

When null is the right call

Use null when something upstream already owns retries and you want the first failure to surface unchanged, for example a queue worker that retries with its own key policy. You then see the raw 429 or 5xx once, instead of the SDK waiting out retry-after inside the call.

Do not use null if your workspace policy requires keys. A service-account key can be configured so that a submit without an Idempotency-Key is refused with service_account_idempotency_required; the fix is to send one, not to retry.

When a string beats the default

The auto UUID protects a single call against a transient failure. It does not protect you when your own process crashes after the create succeeds, because the next start mints a new UUID and creates a second run. For a unit of work you can name, such as an order id plus a revision, pass that string. The onCreated callback is the place to persist the run id the moment it exists.