Not every message arrives, and that is normal. What is not normal is retrying blindly until the retry count becomes the problem itself.
The statuses and what they mean
scheduled — the message was accepted and is waiting for its send time. Nothing has happened yet.
sent — the message left for the carrier. Delivery confirmation has not arrived. Most messages sit here for a few seconds.
delivered — the carrier confirms the message reached the handset. This is the only status that means success.
failed — delivery did not succeed. The reason in the response tells you what to do.
Causes and the correct action
Non-existent or invalid number. Do not retry. Mark the number invalid in your database and stop all future traffic to it. Retrying burns credit with no chance of success.
Handset unavailable. The phone is off or out of coverage. The carrier holds the message and retries on its own for a period. Do not duplicate: you end up with two identical messages delivered at once when the phone returns to the network.
Recipient blocked or opted out. Stop sending permanently. Investigate how the number entered the list.
Message rejected by the carrier. Usually problematic content or sender ID. An identical retry fails identically. Review the text, the sender and the message classification.
Insufficient credit. Top up the account. Messages are not lost if you re-submit after topping up, but they do not send themselves either.
When retrying makes sense
Only for transient failures, and only with exponential backoff: first retry after a minute, second after five, third after fifteen. After three attempts, stop and escalate to an alternative channel.
For OTP codes, automatic retries barely make sense: by the time you retry, the code has expired. Better to give the user a resend button, with a fresh code.
What to monitor
Track delivery rate in hourly buckets, not in totals. A sudden drop signals a routing or content problem, and monthly averages never show it in time.
Track it separately per sender ID and per message type. If transactional deliverability falls while promotional stays flat, you have a routing problem, not a content problem.
The detailed reports in your account show every message with its final status and failure reason — always start there, not from guesses.
