Idempotency and retries
One key per business operation
Section titled “One key per business operation”Idempotency-Key is required when creating a message or batch. Use between 1 and 128 visible ASCII characters.
Choose a stable value associated with your operation: an appointment reminder, for example, should retain its key after a network interruption.
The scope combines the organization, resource and key value. Rotating an API key does not create a different idempotency operation within the same organization.
Reuse the exact request
Section titled “Reuse the exact request”Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.
| Situation | Action |
|---|---|
| Same key and previously processed content | The original response is replayed, except after the erasure described below. |
| Same message request after erasure of its personal data | HTTP 410 personal_data_erased; stop retries and retain the key. |
| Same key with different content | HTTP 409 conflict; correct your business tracking. |
| The same operation is still in progress | HTTP 409 conflict; wait before retrying. |
| Network response lost | Retry with the same key and body. |
| Uncertain provider outcome | Retrieve the message and contact support if needed. |
Retain the submitted values, including sender name and timestamp. Do not change the text or recipient when retrying.
Retain the history
Section titled “Retain the history”V2 idempotency keys are durable. There is no public rule allowing an old key to be reused after 24 hours. Use a new key only for a deliberate new business operation.
Idempotency protects API submissions. It does not promise “exactly once” delivery across every operator.
After erasure of a message’s personal data
Section titled “After erasure of a message’s personal data”After targeted erasure has been reviewed and executed for a completed message, replaying POST /api/sms/v2/messages/ with its original key and content returns 410 with error.code: personal_data_erased. This response replaces the stored creation outcome. It triggers no new send or credit movement.
Stop retrying that operation and retain its key in your tracking. Do not resubmit the message with a new key to bypass the erasure. Different content with the same key remains a 409 idempotency_conflict, including after erasure.
This case applies to replaying the creation of an individual message. Its identifier, status and segment count remain retrievable; the erased message’s to and sender_name fields are empty strings. See the JSON response and required action.
Handle an unknown outcome
Section titled “Handle an unknown outcome”A 502 error for an unknown provider outcome may include message_id. Save that identifier and retrieve its status.
The provider may have accepted the SMS despite the communication failure.
Do not automatically submit the same text with a new key: that could create a second SMS. Never resend a message solely to repair its delivery receipt. See message statuses.