Core concepts
Idempotency
A booking is the one call that costs money and somebody's afternoon, and it is also the one you will retry. Send an Idempotency-Key and a retry returns the delivery you already created instead of a second one.
The problem it solves#
A request can be received, processed and committed, and still look like a failure to you: the connection drops on the way back, your HTTP client times out, your process is redeployed mid-flight. The honest response to "did that book?" is to go and look — and under load, nobody looks. They retry. Without a key, that retry is a second delivery: a second rider dispatched, a second charge, a second settlement row.
How to use it#
Send an Idempotency-Key header on POST /api/v1/dispatch/deliveries. Use the same value for every retry of the same booking.
curl -X POST "https://api.rheochat.com/api/v1/dispatch/deliveries" \
-H "Authorization: Bearer rk_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-4821" \
-d '{ … }'import { RheoChatDispatch, withIdempotencyKey } from "./rheochat-dispatch";
const dispatch = new RheoChatDispatch({ apiKey: process.env.RHEOCHAT_API_KEY! });
const delivery = await dispatch.createDelivery({
pickup, dropoff,
paymentMethod: "cod",
reference: order.id,
// Derive it from your order, not from the clock: a key that changes
// on every attempt is not an idempotency key, it is a nonce.
idempotencyKey: withIdempotencyKey(order.id),
});What happens on a repeat#
| Situation | Response |
|---|---|
| First call with a given key | The delivery is created. 201 with the booking. |
| Repeat with the same key and the same body | The original response, replayed. 201, plus Idempotent-Replay: true. Nothing new is created. |
| Repeat with the same key and a different body | 409 idempotency_conflict. Nothing is created and nothing is replayed. |
| Two identical calls racing each other | One creates the delivery; the other waits, then replays it. Never two deliveries. |
| No key at all | Every call creates a delivery. Idempotency is opt-in; without a key we cannot know two requests are the same one. |
HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replay: true
Cache-Control: no-storeThe body of a replay is byte-for-byte what the first attempt returned — the same id, tracking code and price — because it is stored at the moment the delivery is created rather than recomputed. A price change, an expired promo or a vehicle going offline between your first attempt and your retry therefore cannot make two answers to one booking disagree. The single exception is request_id, which is new each time: it identifies the HTTP request, and support needs it to find this call.
Conflicts#
Reusing one key for a genuinely different booking is a bug in the caller, not a retry. We refuse it rather than hand back an unrelated delivery, because a wrong answer with a 201 on it is far more expensive to find than an error.
{
"error": {
"code": "idempotency_conflict",
"message": "This Idempotency-Key was already used for a different booking. Use a new key for a new delivery.",
"details": { "tracking_code": "DCAB12CD34" }
},
"request_id": "…"
}The comparison is a hash of your request body with keys sorted at every level, so a client that serialises its JSON fields in a different order on the retry — which happens across languages and library versions — is still recognised as the same request. A field you actually changed is not.
Choosing a key#
The key must be derived from the thing you are booking, and it must survive a restart. If it changes between attempts, it is a nonce, and a nonce buys you nothing.
# Good — one stable key per booking attempt
Idempotency-Key: order-4821
Idempotency-Key: 7c9f2b18-3a6d-4c5e-9f01-2b3c4d5e6f70 # a UUID you stored on the order
# Bad — a new key every attempt defeats the whole mechanism
Idempotency-Key: 1737462911 # a timestamp
Idempotency-Key: 8f3a… # a fresh random value per retry- Your own order id is usually the right answer, possibly with a prefix.
- A UUID works, as long as you generate it before the first attempt and store it on the order.
- If one order can legitimately produce two deliveries — a split shipment, a redelivery — include what distinguishes them:
order-4821-leg-2.
| Rule | Detail |
|---|---|
| Length | 1–255 characters. |
| Characters | Printable ASCII. A key travels through logs and support threads; anything else makes those places lie about it. |
| Scope | Per company and per environment. The same string in test and live are two different keys. |
| Lifetime | Permanent. The key stays attached to the delivery it created — there is no 24-hour window after which a replay silently becomes a new booking. |
Permanent means permanent
409, not a new booking. Derive keys from something unique to the booking and this never comes up.The other endpoints#
- Quote is a read. Call it as often as you like.
- Retrieve and list are reads.
- Cancel is idempotent by nature: cancelling an already-cancelled delivery succeeds rather than erroring, so a retried cancel never fails because the first one worked. It takes no
Idempotency-Key.
Which leaves booking as the only endpoint that needs a key — see Book a delivery for the full reference.
A retry policy that works#
- Retry on a timeout, a dropped connection, and on
5xx. - Do not retry on
4xxother than429. The request is wrong; sending it again will not make it right. - Back off exponentially with jitter — 1s, 2s, 4s — and stop after three or four attempts.
- Keep the same
Idempotency-Keyacross every attempt, including attempts made by a later job after your process died.
What the SDK does for you
The JavaScript SDK retries timeouts and 5xx automatically, but it only retries a booking when you supplied an idempotency key. Without one it fails fast and tells you, rather than quietly risking a duplicate on your behalf.