Proposal: Enable retries for non-idempotent operations using client provided "logical request" tokens.

Enable retries for non-idempotent operations using client provided "logical request" tokens.

Not all HTTP methods are guaranteed to be idempotent. This presents challenges when requests fail/no response is received by a client - is the request safe to retry or not?

A client-provided idempotency token/key/value can be used by a service to detect duplicated messages. A client would provide the same value for the idempotency token for each retried request.

Across Microsoft, some services, x-ms-client-request-id ^1 has been used for this purpose.

Unfortunately, many Azure services have been using the same header for a different purpose (arbitrary correlation between client and server side events/telemetry).

Note as changing the meaning of the existing header would be a massively breaking change for clients that assumed that the header had no semantic value for the service.

Other services have similar constructs to facility safe retries of non-idempotent requests: AWS ^2, Stripe ^3

Header name

A new optional Idempotency-Token header is introduced. It's value MUST be a GUID (using the canonical text representation - all lower case without curly braces):

Example:

Idempotency-Token: 475a5eef-de54-4bd1-97a1-f28d0f0146e0

Service guidance

• Services SHOULD support the Idempotency-Token header for non-idempotent requests.

• Services that know do not understand or support the Idempotency-Token header MUST ignore the header and process the request as normal. This is consistent with the general "ignore headers you don't understand" guidance for services.

• Services MUST be able to detect duplicate requests made within 24 hours of each other. Services MAY prune accepted Idempotency-Token header values after 24 hours.

• Services SHOULD repeat the original response when a duplicated request is detected.

• The service should check the Idempotency-Token for duplicates before it performs conditional request checks.

This applies to what is normally idempotent operations as well - for example, a retried DELETE request without an Idempotency-Token may succeed the first time and return a 404 on subsequent retries, whereas it would have continued to return success (200/204) with an Idempotency-Token.

Client guidance

• A client MUST NOT rely on the service supporting the Idempotency-Token header when retrying requests unless the service is explicitly documented as supporting it.

• A client MUST NOT change request (query, body or header) parameters between requests using the same Idempotency-Token value.

• A client MUST NOT reuse the same idempotency token value within 24 hours.

References

No repository files, tests, or entry points are named. Start by reviewing how this repository structures API guidance, then compare the proposed Idempotency-Token semantics and client/service requirements with existing guidance; done means the proposal has a settled, documented direction.