Idempotency-Key Header Behavior Configuration for JSON POST APIs

Answer the exact question

When a JSON POST request contains an Idempotency-Key that the server has already processed, the recommended practice is to return the original successful response (HTTP 200 or 201) along with an Idempotency-Replayed header. A 409 Conflict should be used only when the duplicate request would create a resource that already exists and cannot be safely replayed. If the key is missing or fails validation, the server should reject the request with 400 Bad Request and should not treat it as a duplicate.

Confirmed facts

• Industry‑wide guidance (e.g., Stripe, AWS S3, GitHub) returns the original response with a replay header for duplicate idempotency keys.
• A 409 Conflict is appropriate only when the duplicate would result in a distinct error state (e.g., duplicate unique constraint) that cannot be recovered by replaying the previous result.
• Key validation (format, length, uniqueness) must happen before any side‑effectful processing; invalid keys trigger 400 Bad Request.
• Servers must persist the key and its response until the operation is fully committed to avoid replaying incomplete writes.
• Stale key entries should be purged after a configurable TTL to control storage growth.

Likely explanation (what you might already be doing)

If you currently return 409 Conflict for every duplicate key, you will cause unnecessary retries and may mislead clients into thinking the operation truly failed. Switching to a replay strategy reduces network traffic and aligns with client expectations for idempotent POSTs.

Implementation steps for this case

1. Validate the key – check format (e.g., UUIDv4), length, and that it is not empty. If invalid, 400 Bad Request.
2. Lookup the key – search a key‑value store that maps Idempotency-Key to the stored response and status code.
3. If found:
   • Return the stored status code and body.
   • Set Idempotency-Replayed: true.
4. If not found:
   • Process the request normally.
   • On success, persist the key and the full response (including status code) for the TTL.
   • Return the normal success status (200/201) and body.
5. Conflict scenario – if the operation would create a duplicate unique resource and you cannot replay the original:
   • Return 409 Conflict with an error payload explaining the duplicate.
   • Do not store the key; the client should modify the request or use a new key.

Missing diagnostic detail that could change the recommendation

Do you require the server to treat a duplicate Idempotency-Key that would normally succeed but create a duplicate resource as a normal request (i.e., not return 409) or do you want to enforce strict uniqueness and return 409? This choice affects whether you should replay or reject duplicates in that specific scenario.