Idempotency

Idempotent operations are safe to retry after network failures. The Datamingle API offers idempotency implicitly, through the unique constraint on each resource's natural identifier — there is no Idempotency-Key header today.

Per-resource behavior

Resource	Operation	Idempotent?	Key
Orders	POST	Yes (by order_number)	Duplicate order_number returns VALIDATION_ERROR
Orders	PUT	Yes — state replacement	—
Orders	DELETE	Yes — already-cancelled is a no-op at the service level	—
Inventory	POST (bulk)	Yes — upsert semantics	(location_code, sku_code) pair
Locations	POST	Yes (by code)	Duplicate code returns 409 DUPLICATE
Locations	PUT	Yes	—
Products	POST	Yes (by sku)	Duplicate sku returns 409 DUPLICATE
Products	PUT	Yes	—

Retrying safely

On network timeout

If a POST /orders/ request times out, you don't know whether the order was created.

1. Retry with the same order_number and external_order_id.
2. Expect one of:
   • 201 Created — the first attempt never reached us.
   • 400 VALIDATION_ERROR with "order_number already exists" — the first attempt succeeded; your retry was rejected. Treat as success.
3. Optionally, GET /orders/{external_order_id}/ to confirm state.

On 5xx

Retry with the same body; the server either didn't persist or the response was lost. Either way the resolution is the same as above.

On 4xx (except 409 DUPLICATE on a retry)

Don't retry without changing the request. A 4xx means the request itself is wrong.

Anti-patterns

• Don't generate a new order_number on retry. That creates a real duplicate order, not idempotency.
• Don't treat 409 DUPLICATE as an error when your retry logic is in play — it's a confirmation that the previous attempt landed.
• Don't batch unrelated operations into one bulk POST just to cut requests. If one row fails and the caller retries the whole batch, other rows get re-upserted (still safe, but noisy).