How it works
Include anIdempotency-Key header with a unique string value in your request.
If you send the same request with the same idempotency key within 24 hours,
the API returns the original response without re-executing the operation.
Key behaviors
Response headers
Every response to a request that includes an idempotency key will include:
When a request fails with a transient error (5xx or 429), the response includes:
Error handling
Idempotency keys interact with errors as follows:- 2xx responses: Cached and replayed on retry
- 4xx responses (validation, not found, etc.): Cached and replayed — these represent deterministic outcomes
- 429 Too Many Requests: Not cached — the key is released so you can retry after the rate limit resets
- 5xx responses: Not cached — the key is released so you can retry the operation
Best practices
- Generate unique keys: Use UUIDs, ULIDs, or a combination of meaningful identifiers
(e.g.,
ik_create_invoice_{customer_id}_{timestamp}) - Scope keys to operations: Don’t reuse the same key across different endpoints
- Retry with the same key: If your request times out or you receive a 5xx error, retry with the same idempotency key — the server guarantees at-most-once execution
- Don’t retry on 4xx: Client errors (400, 422, etc.) are deterministic and will return the same error on replay
Key format
- Maximum 255 characters
- Must contain only printable ASCII characters
- We recommend prefixing with a short identifier:
ik_<your_unique_value>
Expiry
Idempotency keys expire after 24 hours. After expiry, the same key string can be reused for a new operation.Which endpoints support idempotency?
All mutating endpoints (POST, PATCH, DELETE) accept theIdempotency-Key header.
GET requests are naturally idempotent and do not support the header.
The event ingestion endpoint (POST /events) is the one exception — it uses
the per-event unique_id field as a natural unique key instead of the
Idempotency-Key header.