409 idempotency_conflict vs idempotency_key_in_use: which one to retry

Retry 409 idempotency_key_in_use and do not retry 409 idempotency_conflict. In Sume's docs the first means another request with the same key is still in flight, and the docs mark it retryable: true. The second means you reused a key with a different body, and nothing ran.

This follows the Sume Create a run and Format API errors docs, read 2026-09-29. The two codes are documented for Format run creates; the job submit table in Generation admission lists idempotency_conflict as well.

What does each 409 mean and what do I do?

What happens on each replay?

The create call documents four replay cases. A body counts as different even when only the instruction or the attachment list changed.

Why do I get idempotency_conflict on a retry?

Almost always because the key or the body is not stable. The docs say to derive the key from the thing being made, such as your order id plus a version you bump on purpose, and not from the moment of asking. A uuidgen per request makes the header decorative, and a body that embeds a timestamp or a reordered field list changes on every attempt.

Two more rules from the same pages: keys are scoped to one Format, so the same key sent to two Formats starts two runs, and a key is up to 255 characters.

How do I retry the in-use case?

Wait about a second, then resend the identical request. Once the first request has finished you receive the original run back as the 200 replay. Do not switch to a new key: that would start a second run.

for attempt in 1 2 3; do
  code=$(curl -sS -o resp.json -w "%{http_code}" \
    -X POST "https://api.sume.com/v1/formats/acme/live-commerce/runs" \
    -H "Authorization: Bearer $SUME_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: order-8823-lc-v1" \
    -d @body.json)
  [ "$code" != "409" ] && break
  grep -q idempotency_key_in_use resp.json || break
  sleep 1
done
cat resp.json

What about retrying a run that failed?

That is a different question. The errors page says to retry a failed run with a new Idempotency-Key, because the old one is bound to the receipt you already hold. When the failure left clips behind, it points you to continuing the run instead of starting a fresh one.