How would you design a POST endpoint so client retries do not create duplicate orders, payments, or records?

Design an idempotent POST endpoint

Makes POST retries return one durable business outcome by combining scoped keys, request identity, atomic ownership, response replay, and reconciliation.

1Say itAnswer out loud first

2CompareCompare with Core answer

3RefineRefine with Stronger and Advanced

TL;DR

I require a client-generated idempotency key for a POST whose duplicate effect would matter. The server scopes it to the caller and operation, stores it with a fingerprint of the meaningful request, and creates the business record atomically with the key. A retry with the same key and request returns the original status and result. Reusing the key with different input is rejected, so one key cannot silently represent two operations.

Full answer below

Practice focus

idempotency keys, retry safety, persistence, uniqueness, partial failure, and distributed correctness

Answer first

Answer path

Core answer first, then checkpoints toward a stronger answer.

Start
Core answer
Start here. This is the direct spoken answer to practice first.
Why this question matters
A client can lose the response after the server commits. Retry safety therefore depends on remembering the logical operation and its outcome, not on hoping the client submits only once.
I require a client-generated idempotency key for a POST whose duplicate effect would matter. The server scopes it to the caller and operation, stores it with a fingerprint of the meaningful request, and creates the business record atomically with the key. A retry with the same key and request returns the original status and result. Reusing the key with different input is rejected, so one key cannot silently represent two operations.
Checkpoint
Stronger answer
Optional upgrade with examples, trade-offs, and sharper phrasing.
The idempotency record has an explicit state such as processing, completed, or failed, plus the resource id and a replayable response reference. A unique constraint lets one concurrent request own a new key while the other observes the existing operation. I do not hold an HTTP request open indefinitely when another attempt is still processing; the API can return the known operation state or a status location. The request fingerprint excludes transport noise but includes every value that changes business meaning. Retention exceeds the realistic retry window, and cleanup never removes active operations. Validation failures that create no side effect normally do not consume the key permanently.

Review signals

Use these to catch weak phrasing, shallow reasoning, and risky claims.

Common mistakesCandidateCommon mistakesMistakes that weaken the answer or signal shallow understanding.Open details

Details

Keeping idempotency keys only in process memory.
Checking for a key and inserting it later without a unique constraint.
Reusing a key for an external retry without reconciling an unknown provider outcome.
Returning a new resource or status on each replay.

How would you design a POST endpoint so client retries do not create duplicate orders, payments, or records?

Practice focus

Answer path

Why this question matters

Review signals

Follow-up prompts

Continue practice

Skill areas

Suggest an improvement