API Idempotency and Retry Semantics

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

## TL;DR

API idempotency lets clients retry uncertain operations without causing duplicate side effects. Retry semantics define which failures are safe to retry, how long to retry, and how backoff should work.

## Core Explanation

Distributed systems often fail after a request is sent but before the client receives a response. Without idempotency, a retry can duplicate a charge, create two records, or send the same message twice. Idempotent HTTP methods and explicit idempotency keys are two common strategies. Retry policies should still be bounded because retry storms can overload a recovering system.

## Source-Mapped Facts

- RFC 9110 defines idempotent methods as methods whose intended effect on the server of multiple identical requests is the same as one such request. ([source](https://datatracker.ietf.org/doc/html/rfc9110))
- Stripe API documentation says idempotency keys let clients safely retry requests without accidentally performing the same operation twice. ([source](https://docs.stripe.com/api/idempotent_requests))
- Microsoft Azure architecture guidance describes the Retry pattern as a way for applications to handle transient failures when connecting to services or network resources. ([source](https://learn.microsoft.com/en-us/azure/architecture/patterns/retry))

## Further Reading

- [RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110)
- [Stripe idempotent requests](https://docs.stripe.com/api/idempotent_requests)
- [Retry pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/retry)