Skip to content
Developers
Pilot. The API is open to a small number of organisations and may change — every change is in the changelog.

Guides

Idempotency

A request that creates something - an order, a product - can fail in a way that leaves you unsure whether it worked: the connection drops after Dnero received it. Retrying it blindly could create it twice.

So every POST takes an Idempotency-Key header: a value you choose, unique to the thing you are creating, such as a UUID or your own order number.

POST /v1/sites/{siteId}/products
Idempotency-Key: 6f1c2a7e-3b8d-4f5e-9a10-2c4b6d8e0f12
  • A POST without one is refused with 400 (idempotency_key_required).
  • The same key with the same body returns the first response, with the header Idempotent-Replayed: true, and creates nothing more.
  • The same key with a different body is refused with 409 (idempotency_key_reused): it is a different request reusing a key.
  • A retry while the first is still being handled is refused with 409 (request_in_progress). Wait a moment and retry with the same key.
  • A key is remembered for 24 hours. A request that failed on Dnero’s side (5xx) is not remembered, so retrying it runs it again.

Keys are per API key: two of your systems choosing the same value do not meet.