Idempotency-Key header to any write request and the server will return the cached response on a retry instead of executing the operation a second time. This is how you guard against duplicate side effects from network failure, browser double-submit, or dispatcher re-delivery. By the end of this page you will know what the key is, when to send it, and the rules the cache enforces.
How it works
Where it applies
Writes that create new resources — minting API tokens, sending invitations, attaching domains — should always carry a key. Without one, a retry creates a second resource.
Key requirements
Cache window
The cached response lives 24 hours from the first successful request. After that, the entry expires and the same key is treated as a new attempt. The window covers dispatcher retries, CI re-runs, and same-day human double-submits. The cache is eventually consistent across regions — propagation is typically under 60 seconds. A retry hitting a different region inside that window may execute again. For payment-class operations, treat idempotency keys as necessary but not sufficient and combine with application-level deduplication.TypeScript SDK
@gavai/sdk-typescript generates and attaches an Idempotency-Key for every POST, PATCH, PUT, and DELETE call. Pass { idempotencyKey } explicitly when you need to control the key across a retry loop:
Next
Errors and retries
Status codes, retry classes, and the
Retry-After contract on 429s.