Making Privy API requests idempotent with idempotency keys
Idempotency keys ensure your API requests to Privy aren’t executed multiple times, preventing duplicated transactions. When provided, Privy guarantees that a request with the same idempotency key will only be processed once within a 24-hour window.
When using idempotency keys with the REST API, include the following header with your request:
A unique identifier for the request, up to 256 characters. We recommend using a V4 UUID.
Idempotency keys are recommended for:
POST
request that triggers state changes or transactionsWhile optional, idempotency keys are strongly recommended for all non-idempotent operations in production environments to prevent double-spends and duplicate transactions.
First Request
When Privy receives a request with a new idempotency key, it processes the request normally and stores both the request details and response for 24 hours.
Subsequent Requests
If the same idempotency key is used again within 24 hours:
Key Expiration
After 24 hours, idempotency keys expire. Using an expired key will result in normal request processing.
Changing any part of the request body while reusing an idempotency key will result in an error. Each unique operation should have its own idempotency key.
Generate a unique, random string for each distinct operation. V4 UUIDs are recommended for their uniqueness properties.
For critical operations, store the idempotency key alongside your transaction records. This allows you to safely retry failed operations with the same key.
Making Privy API requests idempotent with idempotency keys
Idempotency keys ensure your API requests to Privy aren’t executed multiple times, preventing duplicated transactions. When provided, Privy guarantees that a request with the same idempotency key will only be processed once within a 24-hour window.
When using idempotency keys with the REST API, include the following header with your request:
A unique identifier for the request, up to 256 characters. We recommend using a V4 UUID.
Idempotency keys are recommended for:
POST
request that triggers state changes or transactionsWhile optional, idempotency keys are strongly recommended for all non-idempotent operations in production environments to prevent double-spends and duplicate transactions.
First Request
When Privy receives a request with a new idempotency key, it processes the request normally and stores both the request details and response for 24 hours.
Subsequent Requests
If the same idempotency key is used again within 24 hours:
Key Expiration
After 24 hours, idempotency keys expire. Using an expired key will result in normal request processing.
Changing any part of the request body while reusing an idempotency key will result in an error. Each unique operation should have its own idempotency key.
Generate a unique, random string for each distinct operation. V4 UUIDs are recommended for their uniqueness properties.
For critical operations, store the idempotency key alongside your transaction records. This allows you to safely retry failed operations with the same key.