Idempotent Requests

The API supports idempotency for safely retrying requests that only should be performed once. This could be useful if responses are not received due to network connectivity problems. For example, if a response for a request to add an invoice is not received, you can retry the request with the same idempotency key again and be guaranteed that no more than one invoice is added.

We recommend that idempotency key is used in all write operations that might be retried. When retrying a read operation there is no harm in reading the latest data, and therefore we do not recommend using idempotency keys in read operations.

Idempotency key

To perform an idempotent request, add a HTTP header called "Idempotency-Key" with an unique identifier for the request. Subsequent requests with the same idempotency key will return the same result, including errors.

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request. We recommend that the key is a GUID.

Keys are cached for 24 hours and new requests after that with the same key will be handled as new requests.

Idempotency-specific errors

When a subsequent request is received before the original request has been processed, the second request will result in an error with error code "IDEMPOTENCY_REQUEST_IN_PROGRESS", it is safe to retry with the same key at a later time.

Responses are cached for 1 hour, after that a request with the same idempotency key will return an error "IDEMPOTENCY_RESPONSE_EXPIRED". This should normally never happen, if it does investigate why the same idempotency key was used. If it is important to know if the request was processed or not the please contact Merchant Services.

Results are only cached if the API has started processing the request. Errors while sending the request or authentication errors will not be cached, but validation errors will.

If the same idempotency key is used for different type of requests then an error with error code "IDEMPOTENCY_MISS_MATCHING_REQUEST_TYPE" will be returned.