Idempotent Requests

Akahu's API supports the ability to add an idempotency key for safely retrying requests without performing the same opperation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a payment does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one payment is created.

Akahu's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including 500 errors. Apps can safely retry requests that include an idempotency key as long as the second request occurs within 24 hours from when you first used the key (keys expire out of the system after 24 hours).

Sending Idempotency Keys

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to a POST request. Our POST /payments or POST /transfers endpoints are good candidates for including idempotency keys.

Two common ways of generating idempotency keys are:

  • Generate a random key using an algorithm such as UUID v4
  • Derive the key from some data in your app such as an internal id for a payment request

You can identify a previously executed response that’s being replayed from the server by the header Idempotent-Replayed: true included in the response.