Skip to main content
Idempotency keys prevent duplicate operations when network issues or other failures cause you to retry API requests. By including the same idempotency key in repeated requests, the API ensures the operation only happens once, even if you call it multiple times.

​
How Idempotency Works

When you make a request with an idempotency key, the API stores the key along with the request. If you make the same request again with the same key, only the original request is processed. This is especially important for financial operations like creating payouts, where accidentally processing the same payout more than once could incur multiple fees.

​
Using Idempotency Keys

Include your idempotency key in the Idempotency-Key header: 
POST /businesses/business_34ad99/payouts
Idempotency-Key: 11715481-a337-4a46-a33e-3dcdc56c3b51
Content-Type: application/json

{
  "amount": "100.00",
  "currency": "USD"
}
If the request succeeds, you’ll get the normal response. If you retry with the same key, you’ll get the exact same response, confirming that no duplicate operation occurred.

​
Key Requirements

Idempotency keys should be unique for each distinct operation you want to perform. The API recommends using V4 UUIDs to avoid collisions, but any unique string works as long as it follows these rules: The key must be a string that uniquely identifies the operation you’re trying to perform. Keys are only unique per operation ID - the same key can be used for different operations.

​
When to Use Idempotency Keys

Some operations require idempotency keys, while others support them optionally. Operations that modify financial state or create irreversible changes typically require them. Currently, creating instant payouts requires an idempotency key to ensure safe retry behavior when network issues occur.

​
Key Lifecycle

Idempotency keys are tied to the specific operation requests. If you change the request body or other parameters, the API does not reprocess the request with the changes. Keys remain valid for a reasonable time period to handle retry scenarios, but they’re not permanent. They are not searchable or filterable. Use the returned resource IDs from the operations instead.

​
Best Practices

Generate a new idempotency key for each distinct operation you want to perform. When implementing retry logic, always use the same idempotency key for retries of the same operation. This ensures that network timeouts or temporary failures don’t result in duplicate operations.