Basics

Idempotency

Retry a write without writing twice.

Every write endpoint accepts an Idempotency-Key header. Send one whenever the caller might retry — which is every automation platform, because a network blip looks exactly like a slow response and Zapier will try again on its own schedule.

POST /price-matricesIdempotency-Key: 8f14e45f-ea8d-4b1f-9c2a-77bb0f2e6d31

The three answers#

Same key, same body. The first response is replayed verbatim, marked Idempotent-Replay: true, and nothing is written a second time.
Same key, different body. Refused with 409 idempotency_key_reused rather than answered with somebody else's result. Pick a new key.
Same key, still running. 409 idempotency_in_progress — your own earlier request has not finished. Retry it unchanged in a moment.

Keys are remembered for 48 hours. A key whose request failed is released, so you can fix the payload and retry with the same one.

Choosing a key#

A key should identify the intent, not the attempt. A UUID generated once per import run and reused across its retries is right; a UUID generated inside the retry loop is a new write every time, which is the bug this header exists to prevent.

Derive it from your own data

If your importer has a natural identifier — a job id, a batch number, a checksum of the file — use it. Then a rerun of the same nightly file is a replay rather than a second catalogue push, even after your process has restarted and lost whatever it held in memory.

What happens without one#

The write still works; it is simply not replay-protected. For price writes that is survivable — a matrix upsert is addressed by code and replaces the grid, so running it twice leaves the same prices. For creating a lead it is not: a repeat request from the same person is deliberately a new lead in this product, so a retry without a key leaves the dealer looking at two.