Working with the API
Idempotency
Retry any POST safely. The same Idempotency-Key always gets the same answer, so a timeout never creates a second order.
The problem it solves
Networks fail in the worst place: after Ordexs created the order but before your server read the answer. Without protection, your retry creates a second order and the customer gets two parcels.
Sending a key
Every POST accepts an Idempotency-Key header: any string up to 255 characters that is unique to this operation. A UUID is ideal. Generate it once, store it with the job, and send the same value on every retry of that job.
curl -X POST https://api.ordexs.com/v1/orders \
-H "Authorization: Bearer $ORDEXS_API_KEY" \
-H "Idempotency-Key: 3f9c1e2a-7b4d-4c8e-9a1f-5d6e7f8a9b0c" \
-H "Content-Type: application/json" \
-d @order.jsonWhat happens on a retry
| Situation | Answer |
|---|---|
| Same key, same body, first request finished | The stored response, with the original status and the header Idempotent-Replayed: true. Nothing runs again. |
| Same key, first request still running | 409 idempotency_in_progress. Wait a second and retry. |
| Same key, different body | 422 idempotency_key_reused. A key belongs to one request. |
First request failed with a 5xx | Nothing was stored: the retry runs for real. |
Keys are kept for 24 hours. A key is scoped to the API key that sent it, so two integrations can't collide.
Errors other than 5xx are stored too. A 422 stays a 422 for that key: fix the body and send it with a new key.
A second guard for orders: external_id
Orders can carry your own id in external_id (with an optional source_name, such as "chatbot"). Ordexs refuses a second order with the same pair for that store, even without an Idempotency-Key and even days later. You get 409 duplicate_external_id, with the existing order in details.
Use both: the Idempotency-Key for retries of one request, and external_id so the same conversation, cart or ticket can never become two orders.
