Start with evidence, not guesses
When a customer says they did not receive a message, the fastest route to an answer is the message record. Every message has an ID, a status history and, when it failed, an error code. Looking at those first turns a vague complaint into a specific question: did the platform accept it, did the operator accept it and did the handset confirm it?
This guide gives you a repeatable method. It starts with the status, narrows to a cause with a short list of checks and ends with the information support needs if you cannot solve it yourself.
The four stages of a message
- Your request. Your system calls the API. Problems here return an immediate error
- Platform acceptance. Telnxo validates, prices and queues the message
- Operator delivery. The message is routed to the operator who serves the recipient
- Handset delivery. The operator delivers to the phone and reports back
Knowing which stage failed removes most of the guesswork. A problem at stage one is yours to fix in code, at stage two it is usually configuration, at stage three it is registration or content and at stage four it is the recipient's phone or coverage.
Read the status
| Status | Meaning | Next step |
|---|---|---|
| Rejected | Refused before sending | Check sender ID, template and number format |
| Failed | Operator or handset refused it | Read the error code in Logs |
| Sent, not delivered | Handset off or out of coverage | Wait; most networks retry for a period |
| Delivered | Handset confirmed | Check the content and the recipient |
| Expired | Not delivered within the validity period | Resend if still relevant |
The five checks
- Number. International format, active, correct country
- Sender and template. Approved for that country and mapped correctly; in India, the exact registered text
- Content. No patterns that spam filters block, and links to trusted domains
- Balance and limits. Sufficient balance and no channel or rate limit hit
- Consent and suppression. The number is not on a do-not-disturb or suppression list
Delivery delays
Late messages usually have one of four causes.
| Cause | Clue | What helps |
|---|---|---|
| Operator congestion | Delays across many numbers on one network | Wait; spread large sends over time |
| Large burst | Delay grows with campaign size | Pace the campaign |
| Handset state | A single recipient | Ask them to restart or check coverage |
| Wrong route for the traffic type | OTPs delayed behind promotional traffic | Use separate routes and senders for transactional traffic |
Voice and WhatsApp
For voice, check the call detail record for the SIP response code and see the SIP trunk guide. For WhatsApp, the most common failure is sending a free-form message outside the 24-hour window. See templates and the window.
Prevent problems
- Validate numbers before sending and remove ones that repeatedly fail
- Use dedicated senders and routes for OTPs and alerts
- Monitor failure rate by template and country, with alerts
- Test every new template with real values before a campaign
- Keep your webhook receiver healthy so you hear about failures at once
A worked investigation
A customer complains that nine of ten OTP messages arrive but one never did. You search Logs for the destination number and find the message with status failed and an operator error stating the handset was unreachable. The time stamp shows it was sent at 02:10. You check the customer's other messages and find none to that number before. The likely cause is a switched-off phone. You confirm by asking the customer to restart the phone and request a new code. It arrives. The record you kept, message ID, timestamp, error code, was enough to resolve the case without escalation.
Now compare a second case: every message to one operator is delayed by several minutes from mid-morning. Here the pattern across many numbers points to operator congestion. You open a ticket with the evidence and temporarily move OTP traffic to a different route while the operator recovers.
Error code families
Operator error codes differ, but they fall into families. Learning the families lets you act even on a code you have never seen.
| Family | Examples of meaning | Your action |
|---|---|---|
| Number problems | Invalid, unallocated or barred number | Remove or correct the number |
| Handset problems | Switched off, out of coverage, memory full | Retry later; do not treat as a permanent fault |
| Registration problems | Sender or template not registered | Fix registration, then resend |
| Content problems | Blocked by a filter or policy | Change wording and links, then re-register where needed |
| Capacity problems | Throttled or congested | Slow down and retry with back-off |
Retry policy
Retrying blindly wastes money and can look like abuse. Define a policy per failure family: never retry number problems, retry handset problems after a delay, retry capacity problems with exponential back-off and fix registration or content problems before any resend. Cap retries, for example at three, and record each attempt against the original message ID so reports stay accurate.
Building a failure dashboard
A small dashboard prevents most surprises. Chart delivered, failed and rejected counts per hour, split by template and country. Add the median delivery time and the 95th percentile. Alert when the failure rate doubles against the same hour last week, or when the 95th percentile exceeds your service target. These two alerts catch both outages and slow degradation, and they take minutes to build from the data your webhook already receives.
Escalation checklist
If the five checks do not explain the failure, escalate with a complete package so that nobody has to ask a second question. Include the message ID, the destination number, the send time with its time zone, the template or sender used, the status history and the error code. Add whether the problem affects one recipient, one operator or everyone, and whether it started suddenly or built up. Complete reports are usually resolved in a single reply, while partial ones can go back and forth for days.
Further reading
- Telnxo guide: Webhooks and delivery receipts
- Telnxo guide: DLT checklist
Frequently asked questions
Where do I find the error code?
Open the message in Logs. The detail view shows the operator code and a plain-language reason.
Why was my message delivered but the customer says they did not see it?
It may have been filtered into a spam folder, hidden by a handset setting or read on another device. Ask for a screenshot.
How long until a message expires?
It depends on the validity period set for the route. Check your account settings.
Can I resend a failed message?
Yes, once you fix the cause. Resending without a fix repeats the failure.