Skip to content
Vendrix
Sign in

Idempotency

Networks fail. If a request times out you cannot know whether the message was sent. An idempotency key lets you send the same request again without sending a second message.

These examples use a placeholder address. Your console shows the exact address of the API for your workspace.

How it works#

  • POST /messages requires an Idempotency-Key header: 1 to 255 printable ASCII characters. Without it the call fails with idempotency_key_required.
  • Keys are unique per application and are kept for 24 hours.
  • Same key and same body: you get the original status and body again, with Idempotent-Replayed: true. No second message is sent.
  • Same key and a different body: 409 idempotency_conflict.
  • Two requests with the same key at the same moment: the second waits for the first, then gets its answer.
  • If the first request failed with a 4xx, the key is released and you can use it again.
HTTP
HTTP/1.1 202 Accepted
X-Request-Id: req_9a8b7c6d5e4f3a2b1c0d9e8f
Idempotent-Replayed: true

(the same body as the first response)

Choosing a key#

Derive the key from the thing you are sending, for example order-1042-confirmation, and not from the time. A retry then reuses the same key by construction.