Idempotency, retries, and recovery

Create and retain request identity

Operations that change state require exactly one Idempotency-Key header: submitting an item for mapping, candidate expansion, review, ignore, release, setting or restoring a company item mapping, adding a catalog item, and selecting an alternative. The key is 1 to 128 visible ASCII characters. Create a fresh opaque key for each new business operation, do not place it in the JSON body, and do not derive business meaning from it.

• Same key and identical request content replays the persisted outcome.
• Same key with changed content returns an idempotency conflict.
• A replay can report reused as true while retaining the original outcome and completion time.
• Read-only operations, including the read-only POST batch, alternatives, and catalog-usage operations, do not use an idempotency key.
• A missing, repeated, or invalid Idempotency-Key header is rejected with 400 before the operation runs.

Recover an ambiguous result

After a timeout or lost response, retry only when the operation guidance permits it. Reuse the same key and byte-equivalent business content. Never generate a new key merely because the first outcome is unknown; that could create a second operation.

Concurrency

Candidate expansion and mapping actions use result_revision, and review or release also uses expected_mapping_revision. Setting a company item mapping accepts an optional expected_mapping_revision, and restoring one requires it. Retrieve the current state when a stale revision is reported, then make an explicit new decision with a new idempotency key.