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.

That error is a 409 with an empty body. A request sent while the first request with the same key is still running can also get a 409: wait a few seconds and retry with the same key.

The saved answer includes a 400. After you fix a request that got a 400, send it with a new key: the same key with the changed request gets a 409 for the rest of the hour. Acme does not save a 401, 403, 429 or a bank maintenance 503, so retry those with the same key.

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