Idempotency - TapAce

A network error can leave you unsure whether a request worked. Idempotency keys let you retry without issuing a second pass or applying an update twice.

Send a key

Every POST, PATCH and DELETE request needs an Idempotency-Key header. Use a new random value, such as a UUID, for each distinct operation, and reuse it only when you retry that same operation.

Idempotency-Key: 6f1c2b7e-3b1a-4c9e-9d8a-3f8c5b1d9e2a

A request without one is rejected with 400 and the code missing_idempotency_key. GET requests don’t need the header.

How retries behave

You send	TapAce returns
A new key	Runs the request and saves the response.
A key that already succeeded, with the same body	The saved response again, without running the request a second time.
A key that already succeeded, with a different body	`409` with the code `idempotency_conflict`.
A key whose first request is still running	`409` with the code `idempotency_conflict`. Wait and retry.
A key whose first request failed	Runs the request again. Failed responses aren’t saved.

Keys are kept for 7 days. Each key applies to one endpoint, so the same value sent to two different paths counts as two keys.

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request body."
  },
  "requestId": "req_8f3a2c1d9e7b6a54"
}