Code-Memo

Idempotency & Reliability

What idempotency means in APIs

1. Repeating the same request does not change the outcome beyond the first successful application.
2. Safe methods (GET, HEAD, OPTIONS) should be idempotent; PUT/DELETE often are when designed well.
3. POST payments and creates are the usual non-idempotent hot spots.

Why it matters in retries

1. Networks, gateways, and clients retry on timeouts and ambiguous errors.
2. Without idempotency, retries create duplicate charges, orders, or side effects.
3. Define which status codes are retryable (502, 503, 429) vs terminal (400, 404).

Idempotency keys

1. Client sends a unique key (header) per logical operation; server stores outcome mapping for a TTL window.
2. On duplicate key with same payload, return the same response as the first success.
3. On duplicate key with different payload, return 409 or a documented conflict.

Safe retries in distributed systems

1. Combine idempotency keys with exactly-once-ish semantics via dedupe stores or natural keys.
2. Use outbox/inbox patterns for reliable messaging alongside HTTP callbacks.
3. Document at-least-once delivery for webhooks and how signatures + idempotency interact.