Idempotency

Get started

Every write accepts Idempotency-Key . Replaying a key returns the original response and never consumes a ceiling twice. Keys are retained for 24 hours.

One key per logical action

Generate the key when you decide to do the thing, not when you send the request. Every retry of that one action carries the same key; a genuinely new action gets a new one. A UUID v4 is fine, and so is a deterministic string of your own — order_4471:mandate is better than a random value you did not persist.

Node

const key = `order_${order.id}:check`; // persisted with the order async function check(attempt = 1) { const res = await fetch(`${BASE}/mandates/${mandateId}/check`, { method: "POST", headers: { "Authorization": `Bearer ${process.env.SIDAXIS_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": key // same key on every attempt }, body: JSON.stringify({ operation: "payment", amount: 240, currency: "USD" }) }); if (res.status === 429 || res.status >= 500) { await sleep(2 ** attempt * 100 + Math.random() * 100); return check(attempt + 1); // safe: the key makes it a replay } return res.json(); }

What a replay returns

Same key, same body The original response, byte for byte, with the original status. Nothing is created and no ceiling moves. Same key, different body Rejected. A key is bound to the request that created it, so a bug cannot quietly change what you authorised. Key still in flight You get a 409 while the first request is still running. Retry after a short pause rather than starting a second action. After 24 hours The key is forgotten and the same request would execute again. If a retry can still fire a day later, check the resource first.

Where it applies

POST /identity/claims , POST /identity/attributes , POST /mandates , POST /mandates/{id}/check and POST /sessions . Recognitions, revocations and reads need no key: recognition holds no state, revocation is already idempotent, and reads change nothing.

Two different idempotencies This page is about your requests. Incoming webhooks have their own: deduplicate deliveries on the event id , never on an idempotency key. See Webhooks → See also Rate limits → Check an action →