Skip to main content
Four calls create something that costs money or cannot be duplicated cleanly, and each one requires an Idempotency-Key header. Send one and a retry after a timeout returns the first result instead of creating a second business, account, recipient or payout. The header is required, not optional. A call without it is rejected before anything is created.

Where it applies

On all four the key is a UUID. Anything else is rejected before the call reaches the resource.
  • Create a user
  • Create a virtual account
  • Create a payout
  • Create a recipient
No other write declares the header. Updating a user or a virtual account, requesting a quotation and the RFI calls take no key, so a retry there is not de-duplicated by one.

What a key does

Generate a fresh key per operation you intend to perform — not per retry.
  • Same key, same body — you get the original result back. Nothing new is created.
  • Same key, different body — 409. Nothing is created. Send a new key for a new operation, or resend the exact original body to get the first result.
  • Same key, first call still running — also 409. Wait, then retry with the same key and the same body. If the first call succeeded, the retry returns its result.
  • A key whose first call succeeded, however long ago — still tied to that result. Reusing it never creates a new one.
A 409 never means “it worked twice”. It means the key is already spoken for and this request did nothing.If the first call failed or died before storing its response, the key can stay held, and every retry answers 409 the same as for a call still running. When retries keep answering 409 long after the call should have finished, check whether the first one created anything. If it did, use that result. Only if it did not, send a fresh key.A failed call can also release its key. A retry with the same key then runs the operation again, and if the failure came after the write, that retry creates a second one. Before you retry a call that failed, check whether it created anything.