Idempotency - Reap Business Account API

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.

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
}