Understand v1 idempotency limits

Current contract

Store response evidence

• Persist request_id from every mutation response.
• 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 request hash and 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.

Do not infer idempotency from other systems

Documentation CMS publication and internal workers have separate operation, claim, lease, or reconciliation controls. Those contracts do not make the public v1 mutation routes idempotent or exactly once.