API Idempotency Keys and Safe Retries

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

## TL;DR

Idempotency keys and request IDs let agents distinguish safe retries from duplicate mutations.

## Core Explanation

When an API call times out, the client may not know whether the server committed the operation. Retrying without an idempotency key can create duplicate resources, payments, jobs, or messages. Retrying with a documented key lets the server recognize the repeated request.

Agents should inspect whether the operation is idempotent by default, accepts an explicit idempotency key, or requires application-level retry logic. They should also verify whether the same key was reused with the same parameters, because some APIs reject parameter mismatches.

## Source-Mapped Facts

- Stripe API documentation says idempotency supports safely retrying requests without accidentally performing the same operation twice. ([source](https://docs.stripe.com/api/idempotent_requests))
- Google AIP-155 states that providing a request ID must guarantee idempotency. ([source](https://google.aip.dev/155))
- Amazon EC2 documentation describes optional idempotency for some API actions using a client token. ([source](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html))

## Further Reading

- [Stripe Idempotent Requests](https://docs.stripe.com/api/idempotent_requests)
- [Google AIP-155 Request Identification](https://google.aip.dev/155)
- [Amazon EC2 API Idempotency](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)