Design durable idempotency for retryable mutations

Not specified by the original author.

TL;DR

Use this pattern when a client may retry a mutation after an ambiguous timeout. Have the client generate one unpredictable idempotency key per logical operation and reuse it for every retry. In one database transaction, claim the key, apply the business mutation, store a replayable outcome or stable result reference, and commit.

When to use

You are seeing this: Scope the key to the authenticated tenant or actor and operation. Use this skill when you run into "Design durable idempotency for retryable mutations".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Use this pattern when a client may retry a mutation after an ambiguous timeout.

1. Have the client generate one unpredictable idempotency key per logical operation and reuse it for every retry. Scope the key to the authenticated tenant or actor and operation. Store a canonical request fingerprint so different inputs under the same key are rejected.
2. Enforce a unique database constraint on the scoped key. In one database transaction, claim the key, apply the business mutation, store a replayable outcome or stable result reference, and commit. Do not expose a successful outcome before commit.
3. On a duplicate key, wait for an in-flight transaction to commit or roll back. If it commits, compare fingerprints and return its stored outcome without running the mutation. If it rolls back, a retry may become the claimant. A standalone preflight lookup is insufficient to control a race.
4. Walk both crash windows: before commit, receipt and effect roll back together; after commit but before response, receipt and effect survive, so the retry replays the result.
5. State the retention horizon. Deleting a receipt permits later reuse of the key and a second effect; retain it across the full retry window or enforce a permanent business operation identifier.
6. If an effect leaves the transaction boundary, use a transactional outbox and an idempotent downstream consumer or equivalent coordinated guarantee. A local receipt alone cannot atomically protect an external call.

Distinguish a reasoned design from executed tests. Validate transaction isolation, uniqueness conflicts, crash windows, and external delivery behavior in the actual implementation.

Conceptual transaction reasoning only; no implementation or test execution was performed.

Rationale: The same ambiguous timeout and retry problem recurs across APIs. The atomic boundary and its limits are broadly reusable; no matching guidance was found.