Idempotency and retries
Retry shipment requests safely without creating shipments twice.
Every call to Process shipments must send an Idempotency-Key header. The key lets you retry safely. If you don't receive our response, send the same request again with the same key. You get the original result back, not a second set of shipments.
Choose a key
The value is yours to choose. A new GUID for each request is the simplest approach.
- Use 8 to 128 characters: letters, digits, underscore, dot, colon or hyphen.
- Send the header once per request.
- Keys are matched without regard to case.
- Keys are private to your account. Another client using the same value can't affect yours.
A missing, malformed or repeated header is rejected with 400 Bad Request, and no shipments are created.
Resend the exact same body
A retry must repeat the request body byte for byte. The key is tied to a fingerprint of the exact bytes you sent. If you rebuild the same data with a different field order, different whitespace or an optional field left out, we treat it as a different request and reject it.
Keep the body you sent and resend it unchanged.
Use a new key for each new request
Reusing a key for different shipments is refused. This stops a key becoming attached to the wrong parcels.
What happens when you retry
| You send | State of the first attempt | What you get back |
|---|---|---|
| Same key, same body | Finished | The original response again, byte for byte, with an Idempotency-Replay: true response header. No new shipments are created. |
| Same key, same body | Still running | 409 Conflict with a Retry-After header. Wait that many seconds, then send it again to collect the result. |
| Same key, same body | Failed or interrupted | The request runs again. Shipments already created on the earlier attempt aren't created a second time. See Interrupted requests. |
| Same key, different body | Any | 400 Bad Request. The key is already bound to your first request. |
| A new key | Not applicable | Treated as a new request. |
When you get 409 Conflict, don't start a second request with a different key. That would create the shipments twice.
Interrupted requests
If an attempt is cut short by a timeout, a dropped connection or an error on our side, retry it with the same key.
- Shipments that were already created come back with their existing tracking number and a message on
customResponse, instead of a label. We don't send them to the carrier again. Retrieve those labels using the tracking number. - Shipments that weren't created yet are processed as normal.
Because those entries carry a message rather than a label, a retried batch can come back with hasError set on shipments that do exist. Read the message before you treat one as a failure. The message reads: Already created on a previous attempt with this Idempotency-Key; tracking {number}.
How long keys last
We remember keys for 30 days. After that, repeating a key is treated as a new request.