Higgsfield Idempotency-Key: 422 on a changed body, vs Sume 409

Both Higgsfield and Sume let you send an Idempotency-Key on a generation submit, and both return the original job when you repeat the key with the same request. The difference is the conflict: reusing a Higgsfield key with different parameters returns 422 Unprocessable Entity, while Sume returns 409 idempotency_conflict.

Higgsfield's rules

Higgsfield's page says the key is 1 to 255 visible ASCII characters without whitespace, with UUIDs recommended. A key identifies one generation intent in your account and survives API key rotation. A retry with the same key returns the original request_id without creating or charging for another generation, and the replay may show queued even if the original has finished, so check the status URL. The docs warn not to answer a 422 by generating a new key automatically.

Sume's rules

The /v1/videos page says a replay returns the original job, and the admission page lists 409 idempotency_conflict as the case where the same key was reused for a different operation or payload, with the advice to reuse keys only for exact retries. For model: "sume/auto", resolution is a pure function of the normalized request and the catalog version, so an idempotent replay prices and routes identically.

Choosing a key

Derive the key from your own business object, such as an order line and a shot number, and not from a random value made at retry time. That way a crash and restart sends the same key, and the provider returns the same job. Use the same rule on both APIs.

Never mint a fresh key to get past a conflict. A conflict means the request changed, and a fresh key then pays for a second clip.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shot-03" \
  -d '{"model":"seedance-2","prompt":"A product clip on a desk"}'

What it does not cover

Idempotency covers the submit. Status reads, cancels and webhook deliveries are not protected by it on Higgsfield, and your webhook handler still has to deduplicate by id.