Retrying a bulk Format queue: same Idempotency-Key, same queue

Reuse the key. On Sume bulk runs, the same Idempotency-Key with the same concurrency and items returns 202 and the existing queue, so a network timeout on create cannot start your 100 items twice. A different payload under that key returns 409 idempotency_conflict, and details.queue_id names the original queue.

The two outcomes

What is different from a single run

A single Format run signals a replay. A bulk replay does not: it stays 202, and the queue object has no idempotency_hit field. You cannot tell a replay from a first create by the response alone, so decide it on your side: store the key and queue id together before you send.

Rules that follow

• Mint a fresh key per batch, for example a UUID, not one key per client name.
• Keys are scoped to one Format, so the same key on a different Format is a different queue.
• The key can go in the Idempotency-Key header or an idempotency_key body field. The header wins.
• Appending an item to a retried payload is a change: expect 409, not an updated queue.

Safe retry in Python

import json, os, urllib.request

URL = "https://api.sume.com/v1/formats/your-handle/product-promo/bulk-runs"
body = json.dumps({"concurrency": 2, "items": [{"instruction": "clip 1"}, {"instruction": "clip 2"}]}).encode()

def create(key):
    req = urllib.request.Request(URL, data=body, method="POST", headers={
        "Authorization": "Bearer " + os.environ["SUME_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": key,
    })
    with urllib.request.urlopen(req) as r:
        return json.load(r)["data"]["id"]

key = "batch-2026-10-03-a"
print(create(key))
print(create(key))  # same key and payload: same queue id