Idempotency

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_in_flight`. 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"
}

Node.js SDK keys

The SDK generates a key once per mutating method call and keeps it across that call’s internal retries. A second call generates a different key unless you supply one. For an operation that may be repeated by a worker or after a restart, derive a stable key with idempotencyKey("issue-pass", savedOperationId) and pass it in the method’s final options argument. Save the exact request before sending it. See SDK retries and idempotency. PUT event and signing requests do not currently provide stored-response replay, even when the SDK sends a key. Read their current state before repeating a change.

Resume unfinished work

An unfinished request can remain in flight after a crash. After ten minutes from its reservation, a later request with the same key and body can take over. The ten-minute mark does not schedule a retry, so your application must send it again. Track the operation’s original age. After the seven-day retention window, reconcile with the saved result before repeating it. An externalId helps find passes but is not unique. See Retry after a restart.

Getting started

Basics

Guides

Node.js SDK

API keys

Passes

Loyalty cards

Notifications

Templates

Wallet signing

Deployments

Assets

Send a key

How retries behave

Node.js SDK keys

Resume unfinished work

​Send a key

​How retries behave

​Node.js SDK keys

​Resume unfinished work

Send a key

How retries behave

Node.js SDK keys

Resume unfinished work