Idempotent Requests

Akahu's API supports the ability to add an idempotency key for safely retrying payment and transfer requests without performing the same operation 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).

The following endpoints support idempotency keys:

• /payments
• /transfers

Sending idempotency keys

To perform an idempotent request, provide an additional Idempotency-Key: <key> header to a POST request to a supported endpoint.

Two common ways of generating idempotency keys are:

• Generate a random key using an algorithm such as v4 UUID
• 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.

Handling idempotency errors

Akahu may return idempotency-related errors in the following circumstances:

• You are using the same idempotency key as an earlier request, but with a different request payload. In this case Akahu will return a status code of 422 Unprocessable Entity.
• You are using the same idempotency key as an earlier request that has not finished processing (ie. you have made a duplicate request in quick succession). In this case Akahu will return a status code of 409 Conflict.

Using the SDK

If you are using the Akahu JS SDK then this header is already included. However by default the client doesn't retry failed requests, so make sure you set the retries key when initializing the SDK.

const akahu = new AkahuClient({
  appToken: process.env.AKAHU_APP_TOKEN,
  retries: 3 // <-- Retry requests 3 times on network errors
});