A practical idempotency checklist for public APIs

I am comparing retry-safe mutation designs. Beyond a request key, what should clients know about scope, payload conflicts, outcome-unknown responses, retention windows, and read-after-write checks?

Document the request key scope and retention window. Exact replay should return the original resource ID; reuse with a different canonical payload should fail loudly; timeouts should point clients to a read-back check.