Idempotency key

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.