Idempotency

A network failure can leave you unsure whether a POST executed. Send an Idempotency-Key header and any POST becomes safely retryable: the first request runs, its response is stored, and identical retries replay that stored response instead of executing again.

Sending a key

Add the header to any POST. Use a value that uniquely identifies the operation — an order id, a batch id, or a UUID you persist — not a timestamp. Keys are limited to 255 characters.

curl -s https://api.synexcloud.com/v1/imports \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -H "Idempotency-Key: import-batch-2026-07-12" \
  -H "Content-Type: application/json" \
  -d '{ "file": "file_00a1b2c3d4e5f607", "target": "pass_00a1b2c3d4e5f607", "rows": 120, "levels": [] }'

Semantics

• The first request executes normally, and its response is stored for 24 hours, scoped to your API key.
• A retry with the same key and same payload returns the stored response — marked with an Idempotent-Replayed: true header — without executing anything.
• The same key with a different payload fails with 409 idempotency_key_reused.
• If the original request is still executing, a concurrent retry fails with 409 idempotency_key_in_flight — wait and retry.
• Responses with a 5xx status are not stored, so a failed attempt can be retried with the same key.

Choosing a key

Derive the key from something that is stable across retries of the same logical operation:

• Good — order-88213, batch-2026-07-12, a UUID you generate once and persist before the first attempt.
• Bad — the current time, a random value regenerated on each retry, or a key reused across genuinely different requests.

This pairs naturally with 5xx retries: on a server error, retry with the same key and exponential backoff (see Errors).