Skip to content

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.

Shell
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_reuse

Keys 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: true

Nothing 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:

JSON
{
	"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:

JSON
{
  "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#

Python
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.