HeyGen API idempotency key vs Sume: two different 409s

Both APIs take an Idempotency-Key header, but their 409s mean different things. HeyGen's changelog says that on its look endpoints a retry while the original run is in flight returns 409 request_in_progress; Sume's 409 idempotency_conflict means the key was reused for a different operation or payload.

HeyGen details are from its API changelog; Sume's are from Generation admission and Jobs and results, read 2026-09-30.

What does HeyGen say about its key?

For video creation, the changelog says to send an Idempotency-Key header so a retry does not start a second generation. For look endpoints it adds that a retry while the original is in flight returns 409 request_in_progress, and one after it finishes replays the original response.

What does Sume say about its key?

The admission docs recommend an Idempotency-Key for every paid submit that may be retried, and not resubmitting a paid request just because your local worker timed out. The retry rule is explicit: reuse the same key so the retry returns the original job instead of billing a second one.

How should my retry code treat a 409?

Branch on the code, not the status. A request_in_progress means the original is still running, so wait rather than resubmit; an idempotency_conflict is a bug in how you generate keys, because the payload changed under a stable key. Keep a stable key per intent and a new key per new intent.

async function submit(body, key) {
  const res = await fetch("https://api.sume.com/v1/avatar-1.0/talking-video", {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.SUME_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body: JSON.stringify(body),
  });
  if (res.status === 409) throw new Error("key reused for a different payload");
  return res.json();
}

Where else does this matter?

Wrappers that retry automatically are the usual source of duplicate submits; see axios-retry with idempotency keys for generating the key once per request intent.