Idempotency-Key header on any POST request and you can safely retry on failure. The server caches the first response (status code and body) and replays it on retries. Keys expire after 24 hours.
Behavior
All outcomes are cached, including
4xx and 5xx. If the first attempt returned a business error, retries replay that error. Fix the input and use a new key to try again.
401, 422, and 429 responses are not cached and are safe to retry with the same key.
Retry pattern
Recommendations
- Retry on network errors and
429with the same key. These are the only cases where the original request may not have reached the server. - Use a new key after a
4xxbusiness error. The cached error replays on retries; only a new key triggers a fresh attempt. - Persist the key before sending if you need guaranteed retry safety after a client crash.