• 228 destinations
  • No KYC, ever
  • Bitcoin, Monero, USDT and 4 more

DeliverabilityIntermediate7 min readUpdated 18 October 2026

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

Unknown numbers, absent subscribers, carrier filters, expiry: the twelve reasons an SMS fails, what causes each, what you pay and what to do next.

Part 2 of 4 in the path Landing more messages

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. The panel groups failures by reason with the raw code beside each, exports carry the carrier code with every message, and the API's message object holds both, as failure_reason and carrier_code, next to the created_at and sent_at timestamps. Your system hears about each failure as it happens through the message.failed webhook.

Failed messages were handed to a carrier that could not deliver them, so they are billed like any attempt; messages we refuse before sending are rejected and never billed. Per-message records are kept for 90 days and campaign summaries indefinitely, so export the detail if you want to compare failures over a longer period.

Where a message can stop

At any moment a message sits in one of a handful of states, and the difference between them decides what you pay and what you do next. The API reference has the full definitions.

StatusWhat it meansBilled
queuedAccepted, waiting for its send time, its window or its turnNot yet
rejectedRefused before sending, for example an invalid number or content stopped by the filtersNever
sentHanded to a carrierYes, at this point
deliveredThe handset confirmed receiptAlready, when sent
failedThe carrier could not deliver; a reason and a code are attachedYes, it was sent
expiredThe validity period ran out before deliveryYes, once
testSubmitted with a test key: validated and priced, never sentNever

The twelve reasons

  1. Unknown number. The number is not assigned to anyone: mistyped, never issued, or closed. Remove it; it will never deliver. The report removes all unknown numbers from the list in one click.
  2. Absent subscriber. The phone was off or out of coverage and stayed unreachable while the network tried to deliver within the validity period, 48 hours by default. Retry in a later campaign.
  3. Handset or memory full. The phone refused the message, usually for lack of storage. Rare on modern phones; retry later.
  4. Blocked by carrier filter. The operator flagged the content or the sender. Check the sender rule for the destination, avoid link shorteners on strict routes, and reread the text for phishing vocabulary.
  5. Ported number. The number moved to another operator and the message went to the old one. Portability data catches up; 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 the number after two occurrences.
  8. Do-not-disturb list. Markets with a national registry, such as India and Nigeria, block promotional traffic to the numbers on it. Transactional traffic passes; marketing does not.
  9. Invalid sender for route. The operator refused the sender itself. Rare, because when a carrier refuses a name the message falls back to a numeric sender and the report says so. If you see it, compare the sender with the rule on the destination's country page.
  10. Expired. The validity period elapsed while the carrier kept retrying. Reported as expired rather than failed; not billed a second time. A short validity, right for codes, makes this outcome more common by design.
  11. Destination unreachable. A carrier-wide problem, usually visible on the status page. Wait for the incident to close before you resend.
  12. Refused by the operator, no reason given. Some operators return one generic code for everything. Routes are reviewed daily against measured delivery; if the code keeps appearing on one operator, send support a few message ids.

Remove, retry or change

The twelve reasons collapse into three actions.

  • Remove unknown numbers at once and barred numbers after a second occurrence. Sending to them again only buys more failures.
  • Retry later for absent subscribers, full handsets, roaming, ported numbers, expired messages and carrier outages. The network has usually retried already, so an immediate resend rarely helps; include these numbers in the next campaign, or resend a few hours later when the message matters.
  • Change something for filter blocks, do-not-disturb failures and invalid senders. The same text from the same sender to the same numbers will fail the same way: change the sender, the wording or the audience. Relabelling a promotion as transactional is not a fix; it is treated as abuse.

Any resend is a new message, billed again once it reaches a carrier. That is different from retrying an API request that timed out: repeat it with the same Idempotency-Key and you get the original result back instead of a second message.

Handling failures in code

If you send through the API, let the webhook drive your response rather than polling. Put your own identifier in reference, up to 128 characters and echoed in responses and webhooks, so every message.failed event maps straight back to a user or an order. Then branch on the plain reason, not on the raw code, which varies by operator:

  • Unknown number on a sign-up or a code: ask the user to check the number they typed instead of offering another resend.
  • A temporary reason on something urgent: offer one resend after a pause, and cap the attempts.
  • A filter block: alert a person. Automatic resends of the same text only repeat the block, and each one is billed.

Store the carrier_code with the event anyway. It is what support needs to trace a pattern on one operator.

Patterns worth acting on

One failure is noise; a share is signal. Read failures by reason, then by destination and operator, then against the previous send to the same list.

  • A rising unknown-number share means the list is ageing. Clean it from the report with one click, then look at where those numbers came from.
  • A rising filter share on one operator means the content or sender is being flagged there: change the sender type or remove the shortener, and test again on a handset on that network.
  • Failures concentrated in one import point at its source: a form without validation, a partner list, an old export.
  • 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.

For a quick way through a whole report, see reading a delivery report in two minutes.

Preventing the avoidable ones

Several failures can be stopped before the send, where they cost nothing.

  • Clean the file on import. The importer normalises numbers to E.164, merges duplicates and lists invalid rows, which are never sent and never billed. Set a default country when the file uses local formats; preparing a contact list covers the rest.
  • Match the sender to the destination. The sender ID guide explains the three rules and what each shows on the phone.
  • Write for the filters. Brand in the first words, links on your own domain, no urgency theatre, nothing that imitates a bank or a carrier.
  • Set validity to the message's useful life. Ten minutes for a code, because a code delivered after it expired is a support ticket; the default 48 hours for a campaign.
  • Integrate with a test key. It validates and prices requests like a live key, so malformed numbers surface before anything is sent or billed.

What is not a failure

Sent without delivered is not a failure. Most destinations return handset receipts, but a few give carrier acknowledgement only, and there sent is the final positive state; some operators also return receipts late or in batches. The country page says which applies, and the delivery reports page covers how receipts are read. Delivered means the handset has the message, not that anyone has read it. Queued means waiting for a window or a send time, as designed. 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.

Put it into practice.An email address opens the account. Rates are public, payment is crypto, and the test key is free.
Start sending

Something unclear or out of date? Tell us on the support page; corrections are folded back into the guide and the update date changes.