Messages that fail with an error code
A failed status always carries a reason. The first question is which layer wrote it — the platform or the provider.
Read this article →Messages are accepted but not arriving
Every call returns success. Work through this in order — the first four checks do not involve the carrier at all.
Check in this order
Each step either finds the cause or rules out a whole layer, so a wrong guess early costs more than it saves.
Read the status
suppressed means the platform never tried to send it, and no provider investigation will help.
Check messageType
Transactional traffic must declare INFORMATIONAL or TRANSACTIONAL, or a recipient who opted out will have it suppressed.
Check the callback
If you never configured a callback URL, you will never learn that a message failed after submission.
Check for a duplicate
If you retried after a timeout, there may be two messages, and the second one may be the one the recipient sees.
Only then look at the provider
Segments, encoding and errorCode on the failed message tell you whether this is an encoding, routing or carrier-side problem.
The timeout trap
The send endpoint accepts asynchronously. Returning success means the platform submitted the message to the provider, and at that moment it may already have gone out.
So a client-side timeout is not evidence of failure. There is no idempotency key: resending produces a genuinely second message, sent and billed. If you do not have a messageId, look the send up in the console by time window and recipient number instead of resending it.
A message that says delivered and was still not seen
delivered is the provider's report that the handset received the message, which is as far as any platform can see. It does not prove a human read it. Before treating it as a platform fault, confirm the recipient has not filtered the sending number, and that the message did not land in a filtered or spam view.
Keep reading
A recipient received the same message twice
Almost always this is a client-side timeout followed by a resend. Here is how to confirm it, and how to stop it happening.
Read this article →A provider stopped accepting traffic
Telling an account-level failure apart from a bad route, and what failover can and cannot absorb for you.
Read this article →