Field notes / Idempotency

Idempotency keys in practice for POST-heavy APIs

When keys are worth requiring

Any POST that creates money movement, stock reservation, or legally significant records should accept an Idempotency-Key header. GET and PUT with stable URLs already behave; POST does not.

Storage window

Twenty-four hours covers most mobile retry patterns. Batch integrators may need seventy-two hours if they replay overnight files—state that in your docs.

Replay behaviour

On duplicate key with identical body, return the original status and body. On duplicate key with different body, return 409 and explain the mismatch. Silent double-charge is worse than a strict error.

Key format

UUID v4 is fine. Avoid keys shorter than sixteen characters; partners will collide.