Guides
Statuses and error codes
Where a message is, and why it didn't arrive when it didn't.
Statuses#
| status | Final | Meaning |
|---|---|---|
queued | No | Accepted and charged; waiting to be sent, or to be tried again after a temporary problem |
sending | No | Being handed to the network right now. Seen only in GET /v1/messages/{id} |
sent | No | The network accepted every part; the handset's delivery receipt is pending |
delivered | Yes | The handset confirmed delivery |
undelivered | Yes | The network accepted it but couldn't deliver it: the phone was off too long, the number is inactive, the network refused it. Charged |
failed | Yes | We couldn't hand it to a network. Parts that never left are refunded |
Statuses only move forward. A message stays sent until its receipt comes; most arrive within seconds, but a phone that's off can take until the network gives up, often 24 to 72 hours.
Error codes#
Undelivered#
error_code is DLR_ and the receipt's status; error_message carries the network's own error code, as operator receipt stat:UNDELIV err:001.
| error_code | Meaning |
|---|---|
DLR_EXPIRED | The phone was unreachable (off, out of coverage) until the network stopped trying |
DLR_UNDELIV | The network couldn't deliver it: an inactive number, a full inbox, a blocked sender |
DLR_REJECTD | The network refused it, often for the sender ID or the content |
DLR_DELETED | The network deleted it before delivery |
DLR_UNKNOWN | The network didn't say |
Failed#
| error_code | Meaning |
|---|---|
DESTINATION_UNAVAILABLE | That destination can't be reached at the moment. Try again later, or ask us about it |
NETWORK_REJECTED | The network refused the message for good |
SEND_FAILED | The network couldn't take it after repeated attempts |
INVALID_ADDRESS | The number or the sender ID can't be used on that network |
ACCOUNT_SUSPENDED | Your account was suspended before it was sent |
SERVICE_SUSPENDED | Sending was suspended before it was sent |
CAMPAIGN_CANCELLED | Its campaign was cancelled before it was sent |
CONTENT_ERASED | Your data retention erased the text before it could be sent |
EXPIRED | It couldn't be sent within the validity_period you set. Refunded |
While retrying#
While a message waits to be tried again after a temporary problem, GET /v1/messages/{id} shows RETRYING in error_code and how many attempts it's had. That isn't final: the message either goes through or ends failed.
What you pay#
- A message is charged when it's accepted, for all its parts.
deliveredandundeliveredmessages cost the full price: the network carried them.failedmessages are refunded for the parts that never left; the refund shows in Billing.