Idempotent requests

Our API supports idempotency for safely retrying requests without accidentally 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 PIRdoes not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that not more than one request is executed.

To perform an idempotent request, provide an additional idempotencyId in the request body.

An idempotency key is a unique value generated by the client which the server uses to recognise subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 64 characters long. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved because no API endpoint began execution. It is safe to retry these requests.

Follow these tips for using idempotency in your requests:

• Sending the same idempotencyId will ensure that the operation is only executed once, regardless of the number of requests.
• If an error is returned synchronously for a request, the same idempontecyId can be reused later on to make the same request without worrying about repeating the operation.