Skip to main content
Idempotency keys prevent duplicate execution of API requests. Privy processes a request with a given idempotency key only once within a 24-hour window, preventing duplicated transactions.

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 POST request that triggers state changes or transactions
  • Scenarios where network issues might cause request retries
  • Critical operations where duplicate execution would cause problems
Privy treats idempotency keys as optional, but apps should include them for all state-changing operations in production.

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.
Changing any part of the request body while reusing an idempotency key results in an error. Each unique operation requires its own idempotency key.

Error replay behavior

Replay behavior varies by endpoint group:
For RPC, import, and wallet create endpoints, Privy permanently caches a 5xx response against the idempotency key for its 24-hour lifetime. Generate a new key to retry after a server error.
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.

Generating idempotency keys

Generate a unique, random string for each distinct operation. Use V4 UUIDs for best results.

Examples

Store the idempotency key alongside transaction records for critical operations. Retry behavior differs by endpoint. See error replay behavior to determine when to generate a new key.