Skip to main content
Networks fail. If a write times out you cannot tell whether it happened. Send an Idempotency-Key header on a POST that changes data and repeat the exact same request if you did not get an answer:
  • The key is 1 to 64 characters: letters, digits and _ . : -. Use a new key for every new request, for example a UUID.
  • Same key, same body: you get the first answer again, with the header Idempotent-Replay: true. Nothing is done twice.
  • Same key, different body: 409 idempotency_key_reused.
  • Same key while the first request is still running: 409 idempotency_in_progress, with Retry-After. Wait and retry.
  • A request that failed (a 5xx, or a network error) can be retried with the same key and runs again.
  • Keys are remembered for 24 hours, per API key.
Product, price list and customer upserts are already safe to repeat because they send state, so the header is a convenience there. It matters most for orders/{id}/acknowledge and for your own retry wrappers.