How do idempotency and retries work together?

When a request times out, the client cannot tell whether the server failed before or after committing. Retrying is the only way to make progress, but a naive retry can charge a card twice or create two orders. Idempotency turns a repeated request into the same observable outcome.

Server-side idempotency

• The client sends a unique idempotency key, usually a UUID generated per logical operation
• The server stores the key with a fingerprint of the request and the eventual response
• A duplicate with the same fingerprint returns the stored response
• A duplicate with a different payload is rejected as a conflict
• The record needs a TTL, but it must outlive the maximum retry window

CREATE TABLE idempotency_keys (
  key TEXT PRIMARY KEY,
  request_hash TEXT NOT NULL,
  status TEXT NOT NULL,
  response_code INT,
  response_body TEXT,
  created_at TIMESTAMP NOT NULL,
  expires_at TIMESTAMP NOT NULL
);

Retry policy matters as much as deduplication. Use exponential backoff with jitter so many clients do not retry in lockstep. Cap the number of attempts and the total deadline. Add a retry budget so retries cannot exceed a fraction of normal traffic during an outage; otherwise a small failure becomes a retry storm.