Idempotency
Networks fail. An Idempotency-Key lets you retry a request without doing the thing twice — above all, without booking a shipment twice.
How to use it
Send a header Idempotency-Key with a value you choose: 1 to 255 letters, digits and _ . : -. Use one key per real-world action — for example order-1042-booking-1 — and send exactly the same key and body when you retry that action.
- Required on
POST /shipments(booking moves money). Without it you get 400 idempotency_key_required. - Optional on
POST /rates,POST /shipments/{id}/cancelandPOST /webhook-endpoints.
What happens on a retry
| You send | You get |
|---|---|
| The same key and the same body, after the first request finished | The first answer again, with the header Idempotent-Replayed: true. Nothing runs twice. |
| The same key while the first request is still running | 409 idempotency_key_in_use with Retry-After: 2. Wait and retry. |
| The same key with a different body | 422 idempotency_key_reused |
Keys are remembered for 24 hours per application and environment. EviPostal stores every answer once the request has started to run, both successes and 4xx refusals. It does not store 5xx errors, 429s, or requests refused before they ran (bad key, missing scope, invalid body) — retrying those runs them again.