Retrying safely
Send an Idempotency-Key so a retry cannot start the same job twice.
Requests that start a job require an Idempotency-Key header. Repeating a request with the same key
returns the original response and starts nothing new.
curl -X POST "https://fabric.inc/api/v1/brands/$BRAND/imports" \
-H "Authorization: Bearer $FABRIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"fileKey":"...","fileName":"catalog.csv","mapping":{"SKU":"sku"}}'Which requests need one
Anything that starts durable work: imports, exports, enrichment runs and re-enrichment. A timeout on one of these tells you nothing about whether it started, and a blind retry would import a catalog twice or charge for the same products again.
Reads and edits need no key. They are already safe to repeat: setting a value to what it already holds records no history and changes nothing.
Choosing a key
Any unique string up to 255 characters. A UUID per logical operation is the usual choice — per operation, not per attempt, since the whole point is that all attempts share one.
Keys are scoped to your organization and retained for 24 hours. After that the same key is a new request.
What comes back
| Situation | Response |
|---|---|
| First request | The real one — 202 and a job id |
| Retry, same body | The original response, replayed |
| Same key, different body | 409 — the key is spoken for |
| Retry while the first is still running | 409 — try again shortly |
Reuse the key on retry, not a new one
A fresh key on a retry is a new request. That is exactly the double import the header exists to prevent.