--- title: "Idempotency keys: safe retries for AI agents - actionlake" description: "An idempotency key makes a retried write run once: the repeat gets the stored result. Why AI agents need it, how keys are made, and mistakes that defeat them." canonical: https://actionlake.com/glossary/idempotency-key updated: 2026-10-22 --- Platform and integration # Idempotency key An idempotency key is a unique value attached to a write request so that if the same request is delivered twice, after a timeout or a retry, the server performs it once and returns the stored result for the repeat. Updated 22 October 2026 Also called Idempotency-Key header, Idempotent request 3 sources checked **On this page** Connect an agent to every system you run. 100,000 calls free a month. No card. [Start free](https://actionlake.com/console?start=sandbox) ## What it is RFC 9110 calls an HTTP method idempotent when sending it several times has the same effect as sending it once. `GET`, `PUT` and `DELETE` are; `POST` is not. An idempotency key makes a non-idempotent write safe to retry. Stripe's API documentation describes the pattern: the client sends a unique key with a create or update, the server saves the result of the first request, and a retry with the same key gets the saved response instead of a second object. The IETF HTTPAPI working group drafted a standard `Idempotency-Key` header; that Internet-Draft has expired, but the pattern is in wide use. ## Why it matters Agents retry, and so do the layers under them. A response stream breaks, a client times out, a model calls the same tool again "to make sure". Without a key, a retried `create_invoice` creates a second invoice, which someone finds months later in a customer's ledger. ## How it works 1. The client sends a key with the write, or the server derives one from the request itself. 2. The server **claims** the key before sending, so a concurrent duplicate waits or is refused. 3. After the vendor answers, the server stores the result under the key. 4. A repeat within the retention window gets the stored result without touching the vendor. 5. The same key with a **different** payload is refused, never answered with someone else's result. ## Example An agent calls `do` to create an invoice. The connection drops before the response arrives, and the agent calls again with the same arguments. The second call returns the first call's invoice number. The vendor saw one request. ## Common pitfalls - **A new key per attempt.** A key that includes a timestamp or attempt number defeats the purpose. - **Reusing a key for a different request.** Servers should refuse it; silently answering is worse. - **Unknown outcomes.** If the request left and no answer came back, retrying blind may duplicate it. Hold the key and check the vendor first. - **Unordered JSON.** Deriving a key from a body without canonicalising it makes the same request look different. ## How actionlake handles it Every write through actionlake is deduplicated. The key is the agent's own (`idempotency_key` on `do`), or one derived from the tenant, the connection, the action and the body in canonical JSON (RFC 8785), length-prefixed so no field can shift into another. A repeat within 24 hours replays the stored result without touching the vendor, and a replay is free. A duplicate that arrives while the first is in flight is refused with a retry hint; the same key with a different payload is refused with 422. If a write left and its outcome is unknown, after a timeout or a 5xx, it is not re-sent until the claim lapses, and the caller is told to check the vendor first. Writes are never cached, and a single `do` never re-sends a write on its own. See the [API reference](https://actionlake.com/docs/api). ## Questions **Why do AI agents need idempotency keys?** Agents and the transports under them retry after timeouts and dropped connections. Without a key, each retry of a write can create a duplicate record in the vendor's system. **How long should an idempotency key be kept?** Long enough to cover realistic retries. Twenty-four hours is a common window, used by Stripe's API and by actionlake. **What happens if the same key is sent with a different payload?** A careful server refuses it. Serving the first request's result for a different request would hand one caller another caller's answer. ## Related terms - [Tool calling Tool calling, also called function calling, is a language model's ability to answer with a structured request to run a named function with arguments, which the application executes before handing the result back to the model.](https://actionlake.com/glossary/tool-calling) - [Dry run A dry run checks whether an agent's action would succeed, whether it is allowed and what it would cost, by validating the inputs, permissions and connection without sending anything to the vendor.](https://actionlake.com/glossary/dry-run) - [Upstream call An upstream call is one HTTP request that actionlake sent to a vendor's API on your behalf and that returned a definitive, attributable response; it is the unit actionlake meters and bills.](https://actionlake.com/glossary/upstream-call) - [Agent plan An agent plan is a saved, versioned procedure of actions, cross-system joins, loops, waits and approval steps that an AI agent writes once and that then runs the same way on demand or on a schedule, without the model re-deciding every step.](https://actionlake.com/glossary/agent-plan) - [Rate limiting for AI agents Rate limiting for AI agents controls how many requests an agent can make in a time window, both to the platform it calls and to each vendor API behind it, so a fast or looping agent cannot exhaust a shared quota or trigger lockouts.](https://actionlake.com/glossary/rate-limiting-for-agents) ## Sources 1. [RFC 9110: HTTP Semantics, section 9.2.2 Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110#section-9.2.2) IETF · checked 22 October 2026 2. [The Idempotency-Key HTTP Header Field (Internet-Draft)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) IETF HTTPAPI working group · checked 22 October 2026 3. [Idempotent requests](https://docs.stripe.com/api/idempotent_requests) Stripe API reference · checked 22 October 2026 [All 30 glossary terms](https://actionlake.com/glossary) ## Connect an agent. Start free. [Start free](https://actionlake.com/console?start=sandbox) [Read the quickstart](https://actionlake.com/docs/quickstart) 100,000 calls free every month. No card. Hard caps on every key. --- Source: https://actionlake.com/glossary/idempotency-key More: https://actionlake.com/llms.txt