Idempotency keys let you retry POST requests safely. If a request fails due to a network error or timeout, you can resend it with the same key and get the original response back — without creating a duplicate.
How it works
Include an Idempotency-Key header with a unique value on POST requests:
If you send the same request again with the same key:
Generate keys
Use UUIDv4 for unique keys, or derive them deterministically from your own identifiers:
Deterministic keys are useful when you want the same logical operation to always map to the same key — for example, “buy AAPL in portfolio X today” should only happen once regardless of how many times you retry.
Which endpoints support idempotency
Key lifetime
Idempotency keys are cached for 24 hours. After that, the same key creates a new resource. Design your keys so that reuse after 24 hours either doesn’t happen or is intentional.
Best practices
- Always use idempotency keys on
POST endpoints in production. Network failures happen — make your retries safe by default.
- Generate the key before the request, not after. If the request succeeds but the response is lost, you need the same key to retrieve the result.
- Don’t reuse keys across different operations. Each logical operation should have its own key.
- Log your keys. If something goes wrong, the idempotency key helps trace what happened.
