Required headers
Include the following header with REST API requests:string
required
A unique identifier for the request, up to 256 characters. Privy recommends V4 UUIDs.
When to use them
Use idempotency keys for:- Any
POSTrequest that triggers state changes or transactions - Scenarios where network issues might cause request retries
- Critical operations where duplicate execution would cause problems
How idempotency works
1
First request
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.
2
Subsequent requests
The app sends another request with the same idempotency key within 24 hours:
- Matching body: Privy returns the stored response without re-executing the operation
- Different body: Privy returns a 400 error indicating invalid use of the key
3
Key expiration
After 24 hours, idempotency keys expire. Privy processes requests with an expired key as new
requests.
Error replay behavior
Replay behavior varies by endpoint group:Policy violation exception: If any endpoint returns a
POLICY_VIOLATION error, Privy deletes
the idempotency record regardless of status code. The app can retry with the same key after
resolving the policy issue.
