Idempotency Keys Can Expire: How to Retry AI Actions Without Creating Duplicates
RELIABLE AI SYSTEMS
A request key can prevent a duplicate operation, but its lifetime, parameter rules and failure semantics matter. A practical guide to designing agent actions that survive lost responses without quietly repeating their effects.
By Ossam Hashim

The dangerous gap between sending and knowing
An AI agent creates an invoice, receives no response and tries again. If the first request never reached the service, the second attempt may finish the job. If the service created the invoice but its response was lost, that same retry may create a second invoice. The visible symptom is identical; the correct next action is not.
The design problem is therefore larger than retrying errors. The system must preserve the identity of one intended action, understand the destination's duplicate-prevention contract and keep an explicit unknown state until evidence resolves the outcome.
This article focuses on that API boundary, rather than workflow replay or model prompting. The examples are design illustrations, not measured production results. The rules below combine current provider documentation with clearly identified engineering recommendations.
1. Start with the operation, not the HTTP status
HTTP Semantics, RFC 9110 section 9.2.2, defines idempotency in terms of intended server effects: repeating an identical request has the same intended effect as making it once. PUT, DELETE and safe methods are idempotent under the standard's semantics. That does not mean their response codes must be identical, or that the server cannot log each request separately.
The standard says a client should not automatically retry a non-idempotent request unless it knows the operation is actually idempotent or can detect that the original request was never applied. A generic POST endpoint does not acquire that property because a client adds a header named Idempotency-Key. The receiving service must implement and document the behavior.
Before enabling retries, write down the exact endpoint, API version, account scope, key retention rules and supported error cases. Treat a missing contract as a missing safety mechanism, not an invitation to guess.
2. A familiar provider can have different contracts
Stripe's current idempotency reference makes an important distinction. For API v1, once endpoint execution begins, Stripe saves the first result's status and body for a key. A replay returns that saved result, including a 500 error. Retrying the same key is therefore not a general instruction to run the operation again until a success response appears.
The same documentation describes API v2 differently: retries do not repeat successful operations, and Stripe retries failed or partially failed work to completion when possible, returning an updated response. A client written around v1's response-cache mental model should not assume it has fully described v2 behavior.
For v1, parameters must match the original request. Results are not saved when validation fails before execution or a concurrent request conflicts before endpoint execution starts. Keys can be removed after they are at least 24 hours old; reusing a pruned key creates a new request. That is a provider-specific retention rule, not a universal industry default.
The practical consequence is easy to miss: a durable local operation ID can outlive the remote duplicate-prevention window. An old job recovered from a queue must not blindly replay a weeks-old request merely because its local key is unchanged.
3. Preserve one intent across every attempt
A useful implementation pattern is to create a durable operation record before sending the first mutation. Give it an opaque identifier, a canonical request fingerprint, the destination account and endpoint, and the requested business action. Keep credentials and unnecessary personal data out of that identifier.
Generate the identity once per intended action, not once per retry. A new random key on every attempt tells many APIs that each attempt is a new operation. Conversely, reusing an old key for a changed amount, destination or resource is not a safe way to revise the original action.
Record provider request IDs, returned resource IDs, response times and the relevant contract expiry alongside the attempt history. These fields answer different questions: a local ID identifies intent, a provider request ID identifies an interaction, and a resource ID identifies what actually exists.

4. A local lock does not make a remote write atomic
Two workers can both observe that an operation has not completed and both execute it. The AWS Compute explanation of Lambda idempotency describes this race, along with the case where an early side effect succeeds but the completion record is never saved.
Use a conditional claim or appropriate persistence mechanism to stop ordinary concurrent execution of the same local intent. But recognize the remaining gap: a local database transaction normally cannot atomically commit a separate provider's API mutation.
If the worker dies after the remote write but before saving the receipt, the next worker still faces an ambiguous outcome. Provider-side idempotency, a destination resource lookup or a reconciliation process must address that gap. Expiring a lock and sending the action again is not, by itself, a correctness proof.
5. Reconcile facts before starting a replacement
Stripe's error-handling guidance treats connection-error outcomes as indeterminate. It recommends checking the relevant object or listening for webhook evidence, with signature verification before processing webhook events. It also warns that v1 keys can be removed after the retention window.
For an agent integration, make reconciliation an explicit procedure:
- Look up the exact provider resource or operation when its identifier is available.
- Compare the returned account, intended fields and final state with the saved request. A vaguely similar object is not a match.
- Use authenticated event evidence where supported. An event saying that work was accepted is not necessarily proof that the requested final state was reached.
- If a safe replay is supported and still within its documented window, use the same key and unchanged parameters under a bounded retry policy.
- If the evidence remains inconclusive, hold the operation for investigation rather than issuing a replacement with a new identity.
A missing object in one eventually consistent list response may be weaker evidence than a definitive operation-status result. The necessary check depends on the service's own guarantees. The objective is to distinguish confirmed failure from lack of confirmation.
6. Bound retries even when they are logically safe
Duplicate prevention does not make retries free. They still consume capacity, extend latency and can worsen an overloaded dependency. Amazon's Builders' Library guidance recommends backoff, jitter and limits on retries, and explains how retries at several layers multiply load.
Choose one retry owner for the relevant operation. If an SDK already retries, count those attempts before adding another application-level loop. Set an overall deadline and attempt budget, honor applicable service instructions and stop when retries are not improving availability. Backoff controls timing; idempotency controls repeated effects. Neither replaces the other.
7. Exactly-once delivery is not exactly-once business action
Google Cloud Pub/Sub's exactly-once documentation scopes its feature to pull subscriptions and a cloud region, based on Pub/Sub message IDs. It also notes that publish-side duplicates can still result in multiple copies, even when exactly-once delivery is enabled.
A message-delivery guarantee therefore cannot automatically establish that an invoice, shipment or external API action occurred once. Your operation identity must survive the boundary from the message system to the application and the external service. Otherwise two distinct messages can legitimately request the same business effect.
A concrete failure drill
Use a sandbox endpoint before deploying a consequential integration. Submit an invented create-invoice intent with key K, simulate a lost response after the server commits, and restart the worker before its local receipt is stored. The expected behavior is either retrieval of the original invoice or a contract-supported replay of K that resolves to that original action, not creation with a new key.
Then test changed parameters under K, concurrent workers, an expired retention window, a rejected request before execution and duplicated incoming events with different message IDs. Assert both the final external resource count and the local operation state. A test that checks only whether the worker eventually returned success can miss duplicate external effects.
The implementation checklist
- One durable identity per intended action, shared across attempts.
- Endpoint- and version-specific idempotency rules recorded with an expiry policy.
- Concurrency protection, without pretending the local and remote writes are one transaction.
- An unknown-outcome state with a defined reconciliation owner.
- A bounded retry budget that includes SDK behavior.
- Verification of the actual final external state, not only a transport response.
These patterns reduce avoidable duplicate actions, but they do not manufacture exactly-once guarantees for a service that offers none. The reliable agent is the one that knows when to stop and establish what happened.
Sources and image provenance
Source documentation checked November 15, 2026. This is an engineering synthesis, not an independent service benchmark or a claim that one design fits every provider. The two conceptual diagrams were drawn specifically for this article from original shapes and text. No third-party photos, logos, screenshots or copied paper figures are used. The diagrams are illustrations, not evidence of measured performance.
Comments
Post a Comment