The Create-Delivery API supports idempotency for safely retrying requests without accidentally creating the same delivery twice. This is helpful during transient failures caused by network disturbance. For example, when calling Burq APIs, you may want to protect your application from unexpected network delays by setting a timeout on the request. However, when the timeout is triggered, there may not be an easy way to tell whether the delivery ended up getting created after the client disconnected - as such, it may not be clear whether you can safely retry the request. Idempotency key solves this problem by ensuring that any requests using the same key will only be processed once.
To perform an idempotent request, provide a unique value for each of your deliveries under the request header x-idempotency-key when calling the Create-Delivery API.
Burq's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeedes or fails. Subsequent requests with the same key return the same result, including 500 errors.
As callers of the Burq API, it's up to you how you want to generate the idempotency key. We suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys are up to 155 characters long.
All idempotency keys are effective for up to 1 hour. All keys are removed from memory after 1 hour. Any subsequent requests with the same key after the key has expired will be processed as new request.
Note, when idempotency key is provided, Burq does not compare the request payload against any previous request with the same key. As such, if you send a second request with different payload but the same idempotency key, you will receive the response for the first request.
We save results only after the execution of an endpoint begins. If incoming parameters fail validation, or the request conflicts with another request that’s executing concurrently, we don’t save the idempotent result because no API endpoint initiates the execution. You can safely retry these requests.
Currently only the Create-Delivery API accepts idempotency keys. We intend to support idempotency keys in all POST requests over time. You can include the key in other POST endpoints if you want to but they will have no effect until support is added in the future. We do not intend to support idempotency key in GET and DELETE endpoints, as such requests are idempotent by definition. Please do not include idempotency key in GET and DELETE requests. Doing so may result in errors.