Idempotency, replay, source version

Mutations (POST, PATCH, DELETE) support idempotency so you can safely retry after a network error without creating a duplicate. Include an Idempotency-Key header on every mutation — preferably a random UUID v4.

How Idempotency-Key works

The idempotency key scope is determined by four elements:

• integration (your API key),
• HTTP method,
• canonical path,
• Idempotency-Key value.

The same combination identifies one operation. The server stores the first successful response and returns it on repeats.

Practical rule: when retrying, send exactly the same body with the same Idempotency-Key. If you change content but keep the old key, you get a conflict instead of a new write.

Source version and stale conflict

For resources updated multiple times (e.g. product, customer), source_version applies — a monotonic version counter on the source side (your store). On write we compare the sent version with the last known one:

This prevents a late or reordered request from overwriting fresher data. Set source_version to an increasing value on every store change (e.g. millisecond timestamp or your own event counter).

Stored response retention

The response stored for an Idempotency-Key is kept for 7 days. A retry within that window returns the same result. After retention, the same key may be treated as a new operation — do not rely on idempotency for retries more than a week apart.

Safe retry patterns

• Generate the key once per operation — persist Idempotency-Key before sending; use the same value on retry.
• Retry with backoff — for 429 rate_limited and 503 tenant_unavailable, wait (see Retry-After) and repeat with the same key.
• Do not change body on retry — changing content with the same key yields 409 idempotency_key_reused.
• Handle 409 deliberately — idempotency_key_reused means body mismatch; stale_source_version means you have a stale resource version; fetch current state before retrying.

Full code meanings are in Errors. Request signing is in Authentication.