The path in
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset as the epoch second the
window resets. A request over the limit is refused with 429, and its body carries retry_after
in seconds. Limits are covered in Caching & Resilience.
A rate request
A rate request is priced against every courier covering the route, and each quote is stored with an expiry before the response is returned. The stored quote is what makes the price binding: the shipment is later created from the quote, not from a fresh calculation.Creating a shipment
Creating a shipment is a single transaction. It consumes the quote, writes the shipment with the price the quote fixed, records the payment intent, and stamps a tracking number. If any part fails, none of it is applied — there is no state in which a shipment exists at a price that was never quoted, or a quote is consumed without a shipment.1
The quote is validated
An expired quote, or one already used, is refused. This is a
400 naming the reason rather
than a silently recalculated price.2
The recipient is checked
A delivery needs a name, a phone number and an address. A request missing any of them is
refused with a
400 naming the fields, before the transaction opens.3
The shipment is written
Priced from the quote, assigned a tracking number, and left
pending until a carrier takes it.4
Events are queued
Webhook deliveries are queued as part of the same transaction, so an event is never emitted
for a shipment that was not created.
Retrying a write safely
Network failures make retries unavoidable, and a retried shipment creation must not create a second shipment. Send anIdempotency-Key header with the request and the key is recorded with
the shipment it produced.
A repeat of the same key returns the original shipment, unchanged, with status 200 instead
of the 201 the first call returned. The status is the only difference; the body is identical, so
a client that does not distinguish them still behaves correctly. A retry arriving while the first
attempt is still in flight is told to retry rather than being allowed to race it.
The status code is how you tell a creation from a replay:
201 means this call created the
shipment, 200 means an earlier call with the same key did.
