Skip to content
Documentation/
/
/
Idempotency

Idempotent requests

Computer networks are imperfect and, occasionally, an HTTP request might be interrupted during transmission and no response will be delivered to the client program. Typically, you will receive an error from your HTTP request library when this happens.

As you cannot be certain whether the request succeeded or failed before the communication was interrupted, you must repeat the request using the same idempotency key. In this way, the investment API can recognise that it is a duplicate of the previous request and handle it accordingly. This ability to achieve the same, intended results, no matter how often the request is repeated is called "Idempotency".

To make our API idempotent, we require you to use "idempotency keys". If your request contains the same idempotency key as a previous request, that has been successfully handled, the Investment API will know not to repeat the work, but rather to repeat the successful response to the request.

Implementing idempotency

1

Provide an idempotency-key HTTP header with the request. This header must have a randomly generated UUID as its value.
Example idempotency key

idempotency-key: ccb07f42-4104-44ad-8e1f-c660bb7b269c
2

Generate a new and unique idempotency-key value for each new request, but make sure that in case you need to retry a previous request, you use the same idempotency-key value as for the repeated request.

Repeat attempts are recognised as idempotent during a time window of at least 24 hours.

Request that require idempotency keys

The following POST requests require idempotency keys; sending idempotent keys for other endpoints or HTTP methods has no effect: