Idempotency is a technique applied to an API service design to ensure that requested work is only performed once.

It allows you to re-attempt API requests in cases when responses are not received, such as network failures, server crashes, or timeouts.

It is recommended that you leverage this system to retry requests when their status is unknown (for example, when you have not received a response). You should rely on idempotency keys to prevent the accidental duplication of operations (in those cases where calls to Bolt succeed, but failures happen elsewhere in your system’s business logic).

Making an Idempotent Request

Bolt ensures requests are idempotent whenever an Idempotency-Key: {{key}} header is specified for all PATCH and POST endpoints.

For example, if you need to ensure that only a single address is added to a shopper’s Bolt Account. A request might look like this:

curl -X POST "https://api.bolt.com/v1/account/addresses" \
    -H "Content-type: application/json" \
    -H "Idempotency-Key: 7dc1cbcb-h38s-3456-dj46-4cdff3831f1b" \
    -H "X-Api-Key: ${API_KEY}" \

Replayed Responses

An idempotency key can only be reused on an identical request, where the URL, method, body, and all API/Publishable Key headers match.

Replayed responses contain an Idempotent-Replayed header. If a cached response is used, an Idempotent-Replayed: true header is set.

% curl -X POST "https://api.bolt.com/v1/account/addresses" \
 -H "Content-type: application/json" \
 -H "Idempotency-Key: 7dc1cbcb-h38s-3456-dj46-4cdff3831f1b" \
 -H "X-Api-Key: ${API_KEY}" \
 ...
 < idempotent-replayed: true
 ...

Handling Concurrent Requests

Whenever concurrent requests with identical keys are made, only one is expected to succeed and return. Other requests produce an HTTP 409 error code.

To prevent errors during subsequent requests, delay all further requests until the original terminates. Then, respond with the cached response.

Error Handling

Our idempotency middleware processes all requests, including:

• bad requests (400s error codes due to requests that are malformed, unauthorized, forbidden, or otherwise unprocessable) and
• internal server errors (500s due to errors in execution, timeouts, etc.).

Retried requests with the same idempotency key and request body will return the same response and status code. You should only retry bad requests after fixing whatever is causing the failure, and do so with a new idempotency key.

Error Resolution

You can see our list of error codes in our Error Code library.