> ## Documentation Index
> Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> POST /cards and POST /treasury/bank-transfer-confirmations accept an Idempotency-Key so retries can't create duplicates.

Two endpoints accept an `Idempotency-Key` header:

* `POST /cards`
* `POST /treasury/bank-transfer-confirmations`

Send one on every create. If the response never arrives (timeout, dropped
connection), you can resend the exact same request with the same key and get
the original result back instead of a duplicate.

## Behavior

| Situation | Response |
| - | - |
| Same key, same body, first call succeeded | The stored response replays, with header `Idempotency-Replayed: true` |
| Same key, different body | `422 IDEMPOTENCY_KEY_REUSED` |
| Same key while the first call is still running | `409 IDEMPOTENCY_KEY_IN_FLIGHT`; retry shortly |
| The store can't verify the outcome | `503 IDEMPOTENCY_UNAVAILABLE`; check the resource, then retry with the same key |
| First call failed with an error | Nothing is stored, so the key is free to reuse |

Keys live for **24 hours**. Only successful responses are stored, so a
failed request never burns a key.

## Designing keys

Make the key unique per **logical** request, not per HTTP attempt: a UUID,
or built from your own stable reference (`ads-2026-10-CMP-0001`,
`new-card-user_01JZ...`). Re-running a job with the same keys is then safe;
everything already created replays.

```javascript theme={"system"}
for (let attempt = 0; attempt < 5; attempt++) {
  const res = await fetch(`${API}/cards`, {
    method: "POST",
    headers: { "x-api-key": KEY, "Idempotency-Key": key, "Content-Type": "application/json" },
    body,
  });
  if (res.status !== 409 && res.status !== 429 && res.status !== 503) return res;
  await sleep(1000 * 2 ** attempt); // back off, same key
}
```


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