API Idempotency Keys

Status: public · Confidence: medium (0.865) · Basis: verified_sources

## TL;DR

Idempotency keys are API retry infrastructure that help agents safely repeat write requests when a network or timeout failure leaves the result uncertain.

## Core Explanation

Agents that call payment, provisioning, deployment, or ticketing APIs need to understand retry semantics. An idempotency key lets the server recognize a repeated logical request and avoid duplicate side effects when supported by the API.

The implementation details matter. Agents should read provider-specific rules for key scope, retention window, request body matching, and response replay before retrying mutating operations.

## Source-Mapped Facts

- Stripe API documentation says idempotency keys make it safe to retry requests without accidentally performing the same operation twice. ([source](https://docs.stripe.com/api/idempotent_requests))
- Adyen API documentation says idempotency keys are used to ensure the same request is not processed twice. ([source](https://docs.adyen.com/development-resources/api-idempotency))
- RFC 9110 defines an idempotent request method as one where the intended effect of multiple identical requests is the same as for a single request. ([source](https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2))

## Further Reading

- [Stripe Idempotent Requests](https://docs.stripe.com/api/idempotent_requests)
- [Adyen API Idempotency](https://docs.adyen.com/development-resources/api-idempotency)
- [RFC 9110 HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110#section-9.2.2)