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.

book, idempotently
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#

SituationResponse
First call with a given keyThe delivery is created. 201 with the booking.
Repeat with the same key and the same bodyThe original response, replayed. 201, plus Idempotent-Replay: true. Nothing new is created.
Repeat with the same key and a different body409 idempotency_conflict. Nothing is created and nothing is replayed.
Two identical calls racing each otherOne creates the delivery; the other waits, then replays it. Never two deliveries.
No key at allEvery call creates a delivery. Idempotency is opt-in; without a key we cannot know two requests are the same one.
a replayed response
HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replay: true
Cache-Control: no-store

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

409
{
  "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.

keys
# 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.
RuleDetail
Length1–255 characters.
CharactersPrintable ASCII. A key travels through logs and support threads; anything else makes those places lie about it.
ScopePer company and per environment. The same string in test and live are two different keys.
LifetimePermanent. 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

Because keys never expire, a key you reuse next year for a different delivery gets a 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 4xx other than 429. 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-Key across 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.