Events

Retries and idempotency

Safe retries through the externalId; what to retry and what not.

Use a client timeout of about 30 seconds for POST /orders.
Retry timeouts, network errors, 5xx, 429 (after Retry-After) and 409 REQUEST_IN_PROGRESS (after Retry-After: 2) with the same body.
An order is identified by your externalId within the connection:
- same externalId, same body, already received → 200 with the first receipt and duplicate: true;
- same externalId, different body → 409 ORDER_CONFLICT. Use a new externalId for a new order;
- same externalId while the first request is still running → 409 REQUEST_IN_PROGRESS. A request that died more than 60 seconds ago is taken over and finished.
"Same body" means the same JSON value after parsing; key order and unknown fields do not matter.
A refused order (any 4xx) leaves nothing behind. For example, an order refused with 409 STORE_OFFLINE can be sent again unchanged once the restaurant is back online.
Cancels and courier updates are safe to retry (see §8.7 and §8.8).