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
Requests that start long-running work: imports, exports, enrichment runs and re-enrichment. After a timeout on one of these you cannot tell whether the job started, and retrying without a key could import a catalog twice or charge for the same products again.
Reads and edits need no key, because repeating them is already safe. Setting a value to what it already holds records no history and changes nothing.
Choosing a key
Any unique string up to 255 characters. Use one UUID per operation, not per attempt: every retry of an operation must send the same key.
Keys are scoped to your organization and kept for 24 hours. After that, a request with the same key is treated as new.
What comes back
| Situation | Response |
|---|---|
| First request | 202 and a job id |
| Retry, same body | The original response, replayed |
| Same key, different body | 409: that key is already in use |
| Retry while the first is still running | 409: try again shortly |
Reuse the key on retry, not a new one
A retry with a new key is a new request, and can start the same job twice.