Idempotency

Every write accepts an optional header:

Idempotency-Key: any-unique-string-per-logical-request

Retrying with the same key returns the first answer instead of doing the work again, and that reply carries Idempotent-Replay: true.

This matters most for sends. A timeout tells you nothing about whether the message went out; without an idempotency key, retrying is a coin flip between losing a message and sending it twice.

Picking a key

One key per logical request. A UUID per attempt is wrong — it makes every retry a new request. Derive it from something stable in your own system: the order id, the row id, the job id.

Two ways it refuses

idempotency_key_reused (409) means the key was used for a request with a different body. A key stands for one request; reusing it for another hides a bug rather than preventing one.

idempotency_request_in_progress (409) means the first request with that key has not finished. Wait and retry with the same key — you will get the original answer. Generating a new key here is exactly what you are trying to avoid.