Bulk queue idempotency: header or body key, and the header wins

On a Sume bulk queue you can send the idempotency key as the Idempotency-Key header or as idempotency_key in the body. If you send both, the header wins and the body value is ignored. The key is scoped to one Format, so the same string on a different Format makes a different queue.

This is read from the idempotency section of Bulk runs (read 2026-10-06). It matters in a Black Friday week because a batch script that retries on a timeout must never create a second queue of paid videos.

What happens when I send the same key twice?

A replay of the same key with the same { concurrency, items } returns 202 and the queue that already exists. A bulk replay stays 202, unlike a single run, and the queue object has no idempotency_hit field, so you tell a replay from a new queue by comparing the queue id you stored.

Which one should a script use?

Use the header. It is the form every other Sume write uses, and it wins in a conflict, so a body field left over from a template can never override it.

• Mint one key per batch, not one per retry, and store it with the queue id.
• Do not reuse a key after you change an item. Change the key with the batch, or you get the 409.
• There is no queue-level idempotency lock beyond the stored key, and no queue-level webhook.

curl -sS -X POST "https://api.sume.com/v1/formats/yourhandle/gift-guide/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: gift-guide-nov-batch-1" \
  -d '{
    "idempotency_key": "this-body-value-is-ignored",
    "concurrency": 2,
    "items": [
      { "instruction": "Gifts under 25 dollars" },
      { "instruction": "Gifts for a host" }
    ]
  }'

What do I do after a 409?

Read details.queue_id from the error. It names the queue that first used that key, so you can poll it instead of creating a new one. If you really meant a different batch, send a new key.