How long does a Sume Idempotency-Key last? The docs don't say
The Sume docs describe Idempotency-Key replay and the 409 conflict but give no lifetime. What is documented, what is not, and a safe way to design around it.
The Sume docs do not state how long an Idempotency-Key is remembered. They do say the header is supported on submit routes, that a retry with the same key returns the original job, and that the same key with a different payload returns 409 idempotency_conflict.
So do not build anything that depends on a specific window. Treat a key as safe for the short retry loop after a submit that timed out, and track your own job ids for anything longer.
What is documented
Everything below is stated in the docs or visible in the API behavior they describe.
| Question | Answer |
|---|---|
| Where is the header supported? | Submit routes |
| Same key, same payload | Returns the original job |
| Same key, different payload | 409 idempotency_conflict |
| Which errors are safe to retry with the same key? | 429 queue_full, provider_capacity_exceeded, 503 |
| How long is a key remembered? | Not stated in the docs |
Designing without a stated lifetime
Persist the job id the moment a submit returns, keyed by your own record such as an order or shot id. If your process restarts, look the id up first and poll it; submit again only when you have no id at all.
Derive the key from something stable, such as the order id plus a hash of the payload, so a deliberate change in the request gets a new key and avoids the 409.
What not to assume
Do not assume a key from last week still protects you from a duplicate, and do not assume it has expired either. If you need to know, ask Sume support and write down the answer with the date, since it is not in the public docs on the read date above.
There is a cost to being cautious in either direction. If you assume keys expire quickly and always generate a fresh key on every retry, you give up the one protection that stops a duplicate paid job after a lost response. If you assume keys live forever and reuse an old key for a new request with a slightly different body, you hit 409 idempotency_conflict, which is at least a loud failure rather than a silent charge. The conservative middle path is a key per logical request, a ledger of the job ids you got back, and no key reuse across different payloads.
Tradeoffs
A local ledger of job ids is more work than relying on the header, but it is the only thing that survives a long outage. The header covers the short window where the response was lost; the ledger covers everything else.
Sources
Related posts
More in Developers
- Sume job.canceled and job.failed webhooks both say status ERROR
A Sume job.failed and a job.canceled webhook both carry status ERROR and an error object. Branch on the event name, not on status, to tell them apart.
- Sume job status logs_available is false: read events_url instead
A Sume job status carries logs_available, false while diagnostics live behind events_url. Read the events timeline for the lifecycle, not inline logs.
- Sume job webhook: request_id equals job_id, store one
In a Sume job webhook payload, request_id and job_id are the same value. Which to use as your dedupe key, and what else the payload carries.
- Sume jobs list: no next_cursor on the last page ends the loop
GET /v1/jobs returns up to 100 jobs newest first. Pass data.next_cursor back as starting_after, and stop when it is absent. Do not build a cursor yourself.
Written by Sume