📍 Bolt Help / APIs, SDKs, & Webhooks / References / Idempotent Requests
Idempotent Requests
A guide on using Bolt's Idempotency Keys with our APIs.

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.


There is no need to make explicitly idempotent requests on PUT, GET, and DELETE endpoints, as these are idempotent by their nature.

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}" \


Idempotency keys are uniquely generated by you. We recommend using a UUID pattern with a maximum of 255 characters to ensure completely distinctive calls.


Keys expire in 24 hours.

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


It is an error for the same key to be used on requests that are not semantically identical.

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

Response Remedial Actions
In response,Idempotent-Retriable set to true. Back off and retry with the same idempotency key.
Rate-Limit Error Back off and retry with the same idempotency key.
Content Error Fix the request and retry with a new key.
Network Error or No Response Retry with the same key.
Server Error Monitor Bolt for outages or reach out to Bolt Support.

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

Filter by Section
Filter by Topic