Idempotency

Acme APIs support idempotency for safely retrying requests without accidentally duplicating the result. When your API call fails and you are not sure if Acme received the request, Idempotency enables you to safely retry a request without risk of creating a second object or performing the update twice.

For POST requests, in order to perform an idempotent request, you have to provide an Idempotency-Key: <key> header in the request for the endpoint that supports it. The <key> can be any string that uniquely identifies your request, for instance a UUID. Results of requests with Idempotency-Key will be saved and returned on every subsequent request with the same Idempotency-Key. These responses will have the Idempotent-Replayed: true header so you can detect them.

Keys and the associated cached responses are removed from the system automatically after 1 hour. A new request is generated if a key is reused after the original has been removed. For retries, the idempotency layer compares incoming request parameters with those of the original request linked to the original idempotency key, and will return an error response if these don't match.

All GET, PUT and DELETE requests are idempotent by default. Sending idempotency keys in GET, PUT and DELETE requests has no effect.