Skip to main content
Send a unique 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.
Generate one key per logical operation. Use a UUIDv4 or any high-entropy string up to 255 characters. Keep the same key across every retry - never generate a new key on each attempt.

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 429 with the same key. These are the only cases where the original request may not have reached the server.
  • Use a new key after a 4xx business 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.