Idempotency

Every POST request requires an Idempotency-Key header. Repeating a request with the same key and the same body returns the original response and does not move money again.

Idempotency-Key: order-8841-attempt-1

Rules

• The key is a string of up to 255 characters, unique per logical operation.
• Keys are kept for 24 hours.
• A repeat with the same key and body returns the stored response, including 4xx errors, with the header Idempotent-Replay: true. To retry after fixing a rejected request, use a new key.
• The same key with a different body returns 409 idempotency_conflict. The bodies are compared by a hash of the canonical form.
• A repeat while the first request is still running returns 409 idempotency_in_progress with Retry-After.
• 5xx errors are not stored as a final result. Retrying is safe, and the system checks whether the operation was already done.

What to do after a network error or a 5xx

Repeat the request with the same Idempotency-Key. Do not generate a new key, or you may create a second payment or payout.

const key = crypto.randomUUID(); // generate once per logical operation, store it with your order
for (let attempt = 0; attempt < 3; attempt++) {
  const res = await fetch(url, { method: 'POST', headers: { ...headers, 'Idempotency-Key': key }, body });
  if (res.status < 500 && res.status !== 409) return res;
  await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
}

For 409 idempotency_in_progress, wait for the Retry-After interval before repeating.