Understand v1 idempotency limits

Current contract

Store response evidence

• For complaint mutations, retain the Idempotency-Key, complaintReference, version, replayed value, canonical request hash, and x-request-id response header.
• For message and broadcast mutations, persist the request_id response field.
• For direct sends, store each recipient, status, and message_id when returned.
• For broadcasts, store broadcast_id, run_id, status, and your client_reference.
• Keep a caller-owned operation record with terminal reconciliation state. client_reference is echoed context, not a server deduplication guarantee.

Handle an uncertain outcome

1. Step 1

   Stop automatic retry

   A timeout or lost response can occur after a provider or database effect.

2. Step 2

   Inspect known state

   Use stored message evidence or query account broadcast state using the known identifiers and caller reference.

3. Step 3

   Reconcile externally

   Confirm whether the intended effect exists before another mutation.

4. Step 4

   Retry deliberately

   Only issue a replacement after duplicate-delivery or duplicate-campaign risk is understood.

Reconcile uncertain complaint outcomes

A timeout can hide a committed complaint mutation. Retry only the exact same body, operation ID, and expectedVersion to request replay. If the intended body or version is uncertain, read the complaint first and reconcile its current version instead of inventing a new operation.