Idempotency & Retries

• Bind idempotency to request identity intentionally: key, actor, route, payload fingerprint, or operation semantics as appropriate.
• Return a stable replayed result for the same accepted operation when the contract requires it.
• Reject key reuse when the payload or intent does not match the original request.
• Choose retention windows and storage boundaries deliberately.

4. Define client retry behavior

• Retry only when the operation and failure class justify it.
• Distinguish timeout uncertainty from explicit business rejection.
• Use bounded retries, backoff, and jitter for transport or transient failures.
• Keep clients from reusing keys across semantically different operations.

5. Re-check edge cases

• Partial execution and unknown completion after timeout.
• Concurrent duplicate requests.
• Async operations accepted but completed later.
• Expired idempotency records and late retries.

Decision Rules

Quality Bar

• Server behavior on duplicate requests should be defined, not accidental.
• Retry strategy should match failure classes and business semantics.
• Key scope and retention should be explicit.
• Conflict handling should protect against semantic drift under reused keys.
• Clients should know when they may retry and when they must not.

Avoid These Failure Modes

• Do not assume HTTP method semantics alone solve duplicate side effects.
• Do not accept the same idempotency key for different intent.
• Do not let retries run unbounded or without jitter on transient failures.
• Do not treat timeout ambiguity as proof the operation failed.
• Do not promise exactly-once behavior when the system only provides deduplicated or replay-safe behavior.

References

• Retry-safe mutation guide: references/idempotency-playbook.md
• Idempotency review checklist: references/idempotency-checklist.md