Content

API idempotency: a complete guide for AI agents

What an idempotency key actually promises, how to generate and scope one, and what providers guarantee when a retry is already in flight.

Chaitrali Kakde

DevRel Engineer

EngineeringOct 21, 2026

Your agent calls Stripe to issue a refund. The network times out before a response arrives. The agent retries. Was the refund processed before the timeout, or not? Without an idempotency key, you have no safe way to answer that question. The retry becomes a second refund.

An idempotency key solves this. It tells the provider: if you receive a request with this key again, return the original result instead of processing a new one. The guarantee holds for the window the provider retains that key. Send the same key twice within that window and you get one result, not two.

What an idempotency key actually does

Most developers understand the basic mechanism. Fewer understand the limits. The key does not make the underlying operation safe on its own. It does not extend indefinitely into the future. And it only covers the operations a given provider has chosen to make idempotent. Assuming broader coverage than a provider documents is one of the most common mistakes in production.

Stripe documents the Idempotency-Key header with a 24-hour retention window applied to write endpoints. That is a well-documented, strong guarantee and the one most engineering teams model their expectations on. Most email providers do not offer an equivalent for sending a message. Check the provider's current documentation before relying on idempotency for any endpoint, and verify the TTL rather than assuming it matches Stripe's window.

Deterministic keys versus random keys

Two approaches work in production. The choice between them affects how much your system needs to remember across process restarts and timeouts.

A deterministic key is built from the operation and its real identifiers: customer ID, invoice ID, amount, and a timestamp bucket. The same logical action always produces the same key. A retry from any source, including a retry triggered an hour later by a different process, collapses onto the original call. No stored state is required.

A random key, typically a UUID generated once per logical action and reused across retries, also works. The requirement is that the UUID must survive timeouts and process restarts. If the process dies before persisting the UUID, the next run generates a new one and the idempotency protection is lost.

For an agent in a retry loop, deterministic keys are the safer default. The agent does not need to remember anything between retries to stay safe.

[@portabletext/react] Unknown block type "block", specify a component for it in the `components.types` prop

Scope and TTL: the limits that catch teams

Idempotency keys are scoped to an account or API key, not globally unique. The same key string used by two different tenants does not cause a collision. Understanding this matters in multi-tenant agent setups: each tenant's keys are isolated from one another.

TTL is where teams run into surprises. A key that protected a retry five minutes after the first call may not protect a retry five days later once the provider has expired it. Treat the TTL as the real safety window. Verify the current documented TTL before relying on idempotency for any high-stakes operation. Do not trust a blog post written on a different date.

Where agents specifically break this

A human developer who is unsure whether a request went through will wait, check a dashboard, or ask a colleague. An agent in a retry loop retries. That behavioral difference is the entire risk surface.

The agent's reasoning about whether the first call probably failed is not a safety mechanism. The only mechanism that protects against a duplicate action is the API refusing to run the same write twice. When the idempotency key has expired, that protection is gone and the agent has no awareness that it left.

There is a second failure mode: the agent issues a correct key on the first call, the network drops the response but the provider processed the request, and the agent retries without the original key because its retry logic did not preserve it. The retry succeeds as a new request. You now have two actions and no error to trace.

How Swytchcode handles idempotent retries

Swytchcode's execution pipeline retries POST and PATCH calls on rate-limit errors only when an idempotency key is set on that call. No key, no automatic retry of a write. The pipeline covers key handling and backoff behavior consistently whether the call came from a CLI run, an SDK integration, or an MCP client.

The email gap

Email sending is the clearest gap in idempotency coverage. Most email APIs do not document a deduplication mechanism for outbound sends. A retry sends a second email unless you check your own send records before retrying.

The practical pattern for email: record the send attempt in your own database before making the API call. On retry, check the database first. If a send is already recorded for that message and recipient, skip the API call. This shifts the idempotency responsibility from the provider to your system.

FAQ

Does every API support idempotency keys?

No. Support is inconsistent across categories. Email sending APIs are the clearest gap. Check each provider's current documentation for the specific endpoints you are calling. A provider-by-provider breakdown is in which email APIs support idempotency keys.

What happens if I reuse a key with different parameters?

Behavior varies by provider. Some reject the request. Others silently return the original response and ignore the new parameters. Test this against the specific provider and endpoint rather than assuming one behavior or the other.

Can idempotency replace retries with backoff?

No. Idempotency makes a retry safe to attempt. It does not decide when to retry, how long to wait, or what to do after repeated failures. Retry timing and backoff are the job of a durable execution layer. The two concerns work together but are not interchangeable.

What is the safest key format?

A SHA-256 of the operation's stable identifiers, truncated to 32 or 64 characters, works across most providers. Stripe accepts up to 255 characters. Avoid wall-clock timestamps alone because two calls within the same second can produce the same key for different operations.

More content