Docs › Orders

Idempotency & retries

externalId makes every create safe to retry.

Networks fail. Every create is safe to retry because Dragonfly deduplicates on your externalId.

How it works

  • The first POST /v1/orders with a given externalId creates the order: 201, idempotentReplay: false.
  • Any later request with the same externalId returns that existing order: 200, idempotentReplay: true. No second order, no second driver.
  • The window is permanent: an externalId belongs to that order forever.

Recommended retry policy

ResponseRetry?
Network error / timeoutYes, with the same body and externalId.
5xxYes: exponential backoff (1 s, 2 s, 4 s … up to 1 min).
429 RATE_LIMITEDYes, after backing off.
400, 401, 403, 404, 409No. Fix the request first.

Choosing externalId

Use your own system's order number (RX-2026-004471, cater-88412). If one of your orders becomes several deliveries, suffix it (88412-a, 88412-b). Don't reuse an id for a different delivery: you'll get the old order back.

← PreviousCancel an orderNext →Webhooks overview

Something unclear or missing? Tell us.