9.3 Idempotency keys and replay
Network calls fail and get retried. For any request whose duplicate execution would be harmful — charging a card, sending a message — send an idempotency key, and the runtime guarantees the effect happens at most once within a replay window.
Sending a key
Idempotency-Key: <opaque string, ≤256 chars>
The scope of a key is tenant + mount + method + path — the same key on a different path is a different operation.
The four cases
| Situation | Response |
|---|---|
| First arrival | Executes; the response is stored for the replay window (default 24 h; bodies up to 1 MB) |
| Duplicate within the window | The stored response is replayed with Idempotency-Replayed: true — the operation does not run again |
| Duplicate while the original is still in-flight | 409 + Retry-After (no double execution) |
| Same key, different payload | 422 idempotency_key_reuse (the key is being misused) |
So a client that retries after a timeout either gets the original result replayed
(if the first attempt actually succeeded) or a clean 409 to wait on (if it's
still running) — never a second charge.
Reading the replay marker
When you see Idempotency-Replayed: true on a response, the body is the
original execution's result, served from the store — not a fresh run. Treat it
exactly as you would have treated the first response.
Pipelines dedupe automatically
Inside a pipeline, keyed/unsafe steps get auto-generated stable keys derived from the invocation and step position (7.7). So composed effects dedupe across segment retries without any caller plumbing — you don't attach keys to internal steps; the runtime does it so a segment re-run can't double-fire an effect.
When to use a key
- Always for external-facing unsafe operations a client might retry (payments, sends, provisioning).
- The agent surface (9.1) advertises, per action, whether an
Idempotency-Keyis honored — so a tool knows when to send one. - You don't need keys for
pure/idempotentoperations (GET/PUT/DELETE) where a repeat is already harmless.
Idempotency and retries (7.7) are two halves of the same reliability story: retry makes a transient failure recoverable; idempotency makes that retry safe. Next: caching.
← Previous: 9.2 Structured errors · Manual home · Next: 9.4 Caching →