Knowledge & actions · Explore this field ↗ · Implementation · 4 min read
Idempotent conversation actions: retries must not become repeats
Give consequential conversational actions a durable identity so a network retry, duplicate tap, or reconnect can report one operation rather than create several.
Retry-safe action
- 01Confirm request
- 02Create operation
- 03Record state
- 04Return same result
A repeat with changed parameters is a conflict, not an update.
Original conceptual diagram · not a live trace or measured result.Name the operation, not the sentence
Conversation text is evidence of intent, not a reliable transaction key. The same user may reformulate a request, a channel may resend a webhook, and a client may replay an interrupted turn. Create an operation ID at the point where the user confirms a consequential request. Bind it to the authenticated actor, action type, normalized parameters, and an expiry rule. Do not generate a new ID merely because speech recognition punctuated the sentence differently.
The IETF Idempotency-Key draft describes a header field intended to make retrying non-idempotent HTTP requests fault-tolerant. Its utility here is conceptual as well as technical: the retry identity belongs to the requested operation. A transcript ID can help trace the interaction, but it should not decide whether money moved twice.
Write the compatibility rule before storage
When a request arrives with an existing operation ID, compare its action type and normalized parameter fingerprint to the stored first request. If they match, return the known state or result. If they differ, reject the reuse as a conflict and require a new confirmation. Never choose whichever payload arrived last. That rule protects against a client bug that reuses a key for a different order.
Hypothetical worked example: a customer confirms a pickup for parcel P7; the mobile app times out and submits the identical request again. The service returns accepted, operation=op-44 rather than scheduling a second pickup. If the second request says parcel P8 under op-44, it receives operation_key_conflict and does nothing.
Store the outcome before replying
The durable record needs more than a boolean. Store received time, actor scope, normalized fingerprint, state, downstream reference, and the response safe to replay. Persist it atomically with the local commitment where possible. If an external system is involved, record that the call is pending before sending it, then reconcile the returned provider reference. A response sent to the user before this record exists creates a window where a retry cannot be distinguished.
HTTP semantics distinguish safe and idempotent methods from general request handling, but an application action often crosses several systems. Your service must define whether “accepted” means only queued locally, successfully handed off, or completed remotely. Do not use idempotency as a euphemism for pretending an uncertain external result is complete.
Treat unknown as a real state
A timeout after an external call can leave the service unable to prove whether the provider acted. Return status_unknown or reconciliation_pending, with the operation ID, rather than automatically sending the call again. Query by the downstream idempotency key where that integration supports it; otherwise send the case to reconciliation. The user should see a truthful statement such as “we are checking the request” instead of a success claim.
This is where the guide goes beyond a reversibility primer. Reversal answers what can be undone; idempotency answers whether the first thing happened once. Some actions have neither a safe automatic reversal nor a safe automatic retry. Those need a status route and an accountable operator.
Keep transcript and transaction linked, not fused
Record the conversation turn, confirmation presentation, and user acknowledgement as audit context. Keep the operation record as the authority for execution. A new conversation can ask for the status of an old operation without recreating it. An operator can view the transcript under its privacy rules without gaining a way to re-run the mutation from a copied message.
This separation also helps with accessibility and voice recovery. A user saying “yes” twice because captions appeared late is not necessarily authorizing two transfers. The confirmation UI should show the existing operation and offer status or cancellation where the service supports it.
Prove the repeat paths
Test a duplicate client submission, concurrent duplicate requests, a late retry after success, a retry after an unknown outcome, and an ID reused with changed parameters. Assert one local record, one permitted downstream attempt or a documented reconciliation route, and a stable replay response. Monitor key conflicts and long-lived pending operations, not just duplicate counts.
Success is not “no errors.” It is that a user or operator can identify the one operation, its current state, and why a retry did or did not execute. The draft and HTTP standard support the retry and response concepts; they do not choose your retention period, fingerprint algorithm, or domain-specific confirmation rule.
Take it into the review
Operation identity card
| Field | Example value | Why it exists |
|---|---|---|
| operationId | op-44 | stable retry identity |
| actorScope | tenant-7/user-91 | binds authority |
| fingerprint | pickup:P7:morning | detects changed reuse |
| state | reconciliation_pending | reports uncertainty |
| downstreamRef | carrier-882 | supports lookup |
A starting artifact to adapt to your service—not a ready-made policy, compliance certificate or test result.
Primary reading
Sources and limits
These links support the architecture, policy, or product behavior discussed above. Vendor documentation describes vendor features; it is not independent proof of performance. Current details should be rechecked before a production decision.
What the sources establish
The Idempotency-Key HTTP Header Field
The current draft defines an Idempotency-Key field for making retries of non-idempotent HTTP requests fault-tolerant.
Limits: It is a draft and does not define a conversation product’s operation store or confirmation UX.
Checked 2026-09-19 · IETF HTTPAPI Working Group · source publication date not established.
Open original source ↗RFC 9110: HTTP Semantics
RFC 9110 defines HTTP method semantics, including the meaning of idempotence and request-response status handling.
Limits: HTTP method semantics do not guarantee that a multi-system business operation is complete exactly once.
Checked 2026-09-19 · RFC Editor · source publication date not established.
Open original source ↗Procedures and worked examples are editorial synthesis. Preparation/review dates are not claimed historical publication dates.