Idempotency
Contents 26 pages
A request that times out has not necessarily failed. The booking may have gone through; you just did not get the answer. Retrying blindly risks booking the same freight twice; not retrying risks not booking it at all.
Idempotency-Key removes the guess. Send one, and a retry with the same key
returns the original outcome instead of doing the work again.
curl -X POST https://app.shipeasyco.com/api/v1/bookings \
-H "Authorization: Bearer $SHIPEASY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 8f14e45f-ea0f-4a3e-9c7a-2b1d0a6c5e33" \
-d '{ … }'Where it applies#
| Endpoint | |
|---|---|
POST /bookings |
Required. A retry without one could charge a card twice. |
POST /quotes/bulk |
Required. 25 lanes is up to 25 charges against your quote budget. |
POST /shipments/{id}/cancel |
Required. A retry replays the first answer instead of filing a second. |
POST /bookings/preview |
Not used: a preview changes nothing, so it is safe to repeat as it is. |
Every other POST, PATCH, DELETE |
Optional, and honoured if you send one. |
Reads ignore the header.
The rules#
Use a fresh key per logical operation — a UUID v4 is ideal. Reuse it only when retrying that same operation. Never derive it from something that repeats (an order number you might genuinely ship twice, a date).
Any string up to 255 characters works (surrounding spaces are trimmed). An empty
or longer header is refused with 400 idempotency_key_required on any write,
including one where the key is optional — it is never ignored.
The key is scoped to the API key, the method and the endpoint. The same
string on POST /bookings and POST /quotes/bulk are two different keys, and
one organization's keys never collide with another's.
The request is fingerprinted: the concrete path and the body. We hash the parsed JSON with its keys sorted, so reformatting or reordering fields does not make one request look like two. But changing a value does — and so does changing the id in the path. A key used to cancel shipment A and then reused on shipment B is refused, never answered with A's result:
Same key, same path, same body → the original response, replayed
Same key, other body → 409 idempotency_key_reuse
Same key, other id in the path → 409 idempotency_key_reuseKeys live 24 hours. After that the key is forgotten and reusing it does the work again.
The three outcomes#
Replay#
You get the original response — the same status, the same body — plus:
ShipEasy-Idempotent-Replay: trueNothing ran a second time. No card was charged, no lane re-rated.
ShipEasy-Request-Id and the rate-limit headers are this request's own; a
replayed error keeps the original request_id in its body.
Still in flight#
You get 409 request_in_progress:
{
"error": {
"type": "conflict",
"code": "request_in_progress",
"message": "A request with that `Idempotency-Key` is still in flight. Retry in a moment.",
"request_id": "req_4b9e2c7a1f30d856",
"doc_url": "/developers/errors#request_in_progress"
}
}Your first attempt is still running. We claim the key before starting the work, so two concurrent twins can never both execute. Wait a moment and retry with the same key — you will get the replay.
If the first attempt died with us — a crash or a deploy mid-request — before anything durable happened, its claim goes stale after 10 minutes and the next retry with the same key runs the request afresh. A claim on a request that had already moved money is never taken over; that one stays in progress until the key expires, and support can tell you what happened to it.
Reused with a different body#
You get 409 idempotency_key_reuse:
{
"error": { "type": "conflict", "code": "idempotency_key_reuse", … }
}You changed the request but kept the key. Use a new key.
Rejections release the key#
If a request is refused before anything durable happened — a validation error, a
declined card, a missing scope, a 503 api_unavailable because we could not
count it — the key is released. You can fix the payload and retry with the
same key.
That matters: a caller who sends a bad ZIP, corrects it, and retries should get their booking, not a lecture about key reuse.
The one exception is 502 payment_outcome_unknown: the card may have been
charged, so that refusal is recorded like a success. A retry with the same
key replays it — with the same booking_id — instead of charging again. Poll
GET /bookings/{booking_id} for the outcome.
Retrying properly#
BASE = "https://app.shipeasyco.com"
key = str(uuid.uuid4()) # once per booking, OUTSIDE the retry loop
for attempt in range(5):
r = session.post(f"{BASE}/api/v1/bookings", json=body,
headers={"Idempotency-Key": key})
in_flight = r.status_code == 409 and r.json()["error"]["code"] == "request_in_progress"
if not (in_flight or r.status_code == 429 or r.status_code >= 500):
break
time.sleep(2 ** attempt)The key is generated before the loop. Generating it inside would defeat the entire mechanism — that is the one mistake worth checking for in review.
A 502 payment_outcome_unknown replays on every retry; poll the booking
instead.
What it does not replace#
Idempotency keys guard your retries. Underneath, the booking pipeline has its
own guarantees: one shipment per charge, and a quote cannot be booked twice
however you ask. So a second booking of the same quote with a different
idempotency key still fails, with quote_already_booked (or
booking_already_paid) and the existing booking_id — the key protects the
retry, the domain protects the freight.