Fundamentals
Idempotency
Idempotency protects state-changing requests from being processed twice after
a timeout, network error, or ambiguous response. It uses the
Idempotency-Key request header.
Send the header on every endpoint that lists it in the API Reference.
Rules
| Situation | Which key to use |
|---|---|
| Retry after a timeout or dropped connection | Reuse the same key. |
| Retry after an unclear response | Reuse the same key. |
| Start another operation | Generate a new key. |
| Change the endpoint, body, or resource scope | Generate a new key. |
Make a GET or list request | No key is needed. |
Use a non-empty ASCII string up to 255 characters. UUIDs are recommended but not required.
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890For client operations, the client path is part of the operation scope. Retry
with the same clientId, body, endpoint, and key.
Idempotency-Key is for retry safety. X-Request-Id traces one HTTP attempt.
They are not interchangeable.