> ## Documentation Index
> Fetch the complete documentation index at: https://tapace.lk/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Retry requests safely without creating duplicates.

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.

```bash theme={null}
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.

```json theme={null}
{
  "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](https://tapace.lk/docs/sdk/node/reliability.md).

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](https://tapace.lk/docs/sdk/node/reliability.md#retry-after-a-restart).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.