Skip to main content
Omneya
EN
Start test system Try it
Developer docs menu

Retries and duplicate protection

Why sending the same order twice never creates two orders, which errors to retry, and how to retry safely.

Duplicate protection with external_order_id

Every order you send carries your own order number in external_order_id. For each API access, one external_order_id leads to at most one order in the shop. This holds even if two requests with the same number arrive at the same time.

Request Response
First request with APP-100234 201 Created, the new order
Any later request with APP-100234 200 OK, the existing order, "duplicate": true
Later request with APP-100234, but the order was deleted in the shop 409 order_deleted

A repeated request creates nothing. The response shows the order as it is now:

{
  "data": {
    "id": 48211,
    "order_number": "48211",
    "external_order_id": "APP-100234",
    "duplicate": true,
    "customer_id": 9021,
    "customer_created": false,
    "status_id": 1,
    "status": "Incoming order",
    "payment_method_id": 3,
    "referrer_id": 17,
    "shipping_method_id": 4,
    "shipping_method": "Parcel",
    "shipping_cost_gross": 4.9,
    "shipping_cost_source": "app",
    "items": [
      { "sku": "SKU-1001", "quantity": 2, "unit_price_gross": 29.9, "price_source": "app" }
    ],
    "grand_total_gross": 64.7,
    "currency": "EUR"
  },
  "warnings": []
}

On a repeat, customer_created is always false and warnings is always empty, even if the first request created a customer or returned warnings.

Points to keep in mind:

  • external_order_id is compared exactly, including upper and lower case. Leading and trailing spaces are removed.
  • The protection applies per access. The same number sent with a key of a different access creates a separate order. Renewing a key does not change the access.
  • A repeat returns the existing order unchanged. If you change the data and send it again with the same number, the changes are ignored. To correct an order, contact the operator.
  • The request is checked before the duplicate lookup. A repeat with invalid data answers 422, and a repeat while the access is misconfigured answers 422 client_not_configured, even if the order exists.

When to retry

Situation Retry?
Connection lost, timeout, no response Yes, with unchanged data
429 rate_limited Yes, after Retry-After seconds
500, 502, 503, 504 Yes, with unchanged data and increasing wait time
200 with duplicate: true No, the order exists. Store its id.
422 No. Fix the data first.
409 order_deleted No. Inform the operator.
401, 403, 404, 405 No. Fix the key, scope or request.

If you do not know whether a request reached the shop, for example after a timeout, send it again with the same external_order_id and the same data. Either the order is created now (201), or you receive the one created by the first attempt (200, duplicate: true).

Backoff

Double the wait time after each failed attempt, for example 2, 4, 8, 16 seconds, and stop after a fixed number of attempts. If the response contains Retry-After, wait at least that long. Keep failed orders in a queue in your app so they are not lost while the shop is unreachable.

attempt 1  -> timeout
wait 2 s
attempt 2  -> 503
wait 4 s
attempt 3  -> 201 Created

Other write requests

Duplicate protection by number exists for orders only. For customer endpoints: