Idempotency

Networks fail. If a POST times out, you don't know whether it was applied, and retrying blindly could create a duplicate product. The Idempotency-Key header solves this:

curl -X POST https://api.nembol.com/rest/v1/products \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: 7d5c1f6e-2f5b-4a1e-9c3d-0a8b7c6d5e4f" \
  -d '{ "title": "…" }'

• Generate a unique key per logical operation (a UUID is perfect), and reuse the same key when retrying that operation.
• Replaying the same key with the same payload returns the stored original response (identical status code and body, plus the header Idempotent-Replayed: true). Nothing is re-executed. Errors are stored too: a 4xx (e.g. a 422) is replayed as it was, even if the cause has since been fixed on your side or ours, so send a new key after changing the request or after a fix. A 5xx is never stored: retrying with the same key runs the request again.
• Replaying the same key with a different payload fails with 409 (idempotency_key_reused). Keys are never silently reused.
• Keys are remembered for 24 hours; max length 255 characters.

Supported (and recommended) on every POST, PATCH and DELETE endpoint.

Retry recipe: on timeout or 5xx, retry with the same key and exponential backoff (e.g. 1s, 2s, 4s, …); on 429, wait Retry-After then retry with the same key.

Last updated on October 17, 2026