Skip to main content

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 "Walley-Idempotency-Key" with an unique identifier for the request. Subsequent requests with the same idempotency key will return the same result, including errors. As an example, add the following HTTP header to the request:

Walley-Idempotency-Key: AD9ACA8B-AD55-45F9-870D-4DA896EAEE35

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". If this happens make sure that the subsequent requests are sent within an hour.

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. If this happens, check the generation of keys to make sure that a unique key is generated and that the key is not reused for different requests.