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, 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. Retry the original request rather than starting a new one.
- A key older than 24 hours — forgotten. The record expires, and the same key creates a second operation.
A 409 never means “it worked twice”. It means the key is already spoken for and this request did nothing. Treat it as a signal to look up the first result, not as a failure to retry with the same key.One case has no first result to look up: if the original call died between taking the key and storing its response, the key stays held for the rest of its 24 hours and every retry answers 409. Send a fresh key rather than polling.
