API guide
Retry without repeating an operation
One key per business operation
POST /messages, campaign send and event ingestion require Idempotency-Key. Other POST endpoints support it where the API reference lists the header. Embedded session creation does not support idempotency and must not be retried automatically. For SDK writes, supply and persist your own key if recovery must survive a restart or exhausted retries. SDK-generated keys only persist within that call. Use a unique value such as order_1042_shipping, and reuse exactly the same key and body when retrying that operation.
A completed response is replayed with Idempotent-Replayed: true. Reusing a key for a different request returns idempotency_key_reused. Completed responses are retained for 24 hours; do not use an old key as a permanent business deduplication record.
Treat an unknown outcome carefully
A timeout does not prove that nothing happened. Retry with the original key, never a fresh one just because the HTTP request timed out. request_in_progress means the outcome is still being reconciled. Check the resource and request logs, and contact support with the request ID if it persists.
Completed server-error responses are also replayed: a mutation may have committed before its response failed. Uncertain interrupted requests are held for reconciliation instead of being automatically rerun. Do not create a new key to bypass that protection. A completed message with status: failed is a separate case: the original request still replays the original message. Inspect its failure reason before deciding to create a replacement message with a new key. For send_interrupted, delivery is uncertain: reconcile with the recipient or provider first; a replacement can send a duplicate.