Twelve reasons an SMS fails, and what the report tells you

Reading a failure

A failed message carries two things: the raw code the carrier returned and a plain-English reason we map it to. The raw code differs from one operator to the next; the reason is the same everywhere so you can act on it. Both are in the panel, in exports and in the message.failed webhook. Failed messages were accepted by a carrier that could not deliver them, so they are billed like any attempt; messages we refuse before sending are rejected and never billed.

The twelve reasons

1. Unknown number. The number is not assigned. Remove it; it will never deliver.
2. Absent subscriber. The phone was off or out of coverage for the whole validity period (48 hours by default). Retry in a later campaign.
3. Handset or memory full. The phone refused the message. Rare; retry later.
4. Blocked by carrier filter. Content or sender flagged by the operator. Check the sender rule and avoid link shorteners on strict routes.
5. Ported number. The number moved to another operator and the route did not follow. We re-route automatically; a retry usually delivers.
6. Roaming unreachable. The subscriber is abroad on a network that does not accept the message. Retry later or accept the loss.
7. Barred subscriber. The line is suspended, often for unpaid bills. Remove after two occurrences.
8. Do-not-disturb list. Markets with a national DND registry, such as India, block promotional traffic to registered numbers. Transactional templates pass; marketing does not.
9. Invalid sender for route. Prevented before sending in almost every case, because the platform swaps the sender; appears only when replacement is disabled by you.
10. Expired. Validity elapsed while the carrier kept retrying. Reported as expired rather than failed; not billed a second time.
11. Destination unreachable. A carrier-wide problem, usually visible on the status page. Wait for the incident to close; queued messages resume.
12. Rejected by operator, no reason. Some operators return a generic code. We flag the pattern per operator; if it repeats, the route is reviewed.

Patterns worth acting on

One failure is noise; a share is signal. A rising unknown-number share means the list is ageing: clean it from the report with one click. A rising filter share on one operator means the content or sender is being flagged: change the sender type or remove the shortener. A sudden jump across all operators of one country is a route problem, and it is our job: it will be on the status page, usually before you notice.

What is not a failure

Sent without delivered is not a failure. Some operators return receipts in batches or not at all; the country page says which. And rejected is not a failure either: it is the platform refusing to send something that would have failed, and refusing to bill you for it.

Something unclear or out of date? Write to [email protected]; corrections are folded back into the guide and the update date changes.