Retries and Idempotent Requests

The 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, suppose a request to the API fails due to a network connection error. In that case, you can retry the request with the same idempotency key to guarantee that only a single registration is created.

An idempotency key is a unique value generated by the client that the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs (GUID), or another random string with enough entropy to avoid collisions. Keys expire after 10 minutes, so a new request is generated if a key is reused outside of that time frame.

To perform an idempotent request, provide an additional "X-Idempotent-ID: [key]" header to the request. The X-Idempotent-ID can only be used with these request methods:

• POST: In this API it is mandatory to use an idempotency key. Idempotency keys are important for POST requests, as they otherwise might erroneously create an additional data object for each retry.

• PUT and DELETE: These requests are idempotent by definition (it will not have any effect on the data if they are called more than once). But retries will return errors that can cause exceptions in some clients, e.g. HIMSA’s .NET API Client. By using idempotency keys, the failed attempts will be hidden from the client. Therefore, in this API they are optional but recommended.

Our idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, but only if it succeeded. Subsequent requests with the same key return the same result.

GET requests are idempotent by definition, meaning that the same backend work occurs no matter how many times the same request is issued. You shouldn't send an idempotency key with these verbs because it has no effect.