An OTP crosses four layers before the user sees it, and each layer fails differently: the application that requests the code, the gateway that routes it, the carrier that delivers it, and the handset that receives it.
The layers also map to owners: the application team owns the request, the messaging team owns the gateway and SIMs, the carrier relationship owns the route, and support owns the handset. Clear ownership is what makes the runbook executable.
Most troubleshooting fails because teams fix the wrong layer, changing content when the SIM was throttled, or rotating SIMs when the bank blocked the sender. This guide maps symptoms to layers and gives the fix order, with the SMS modem and gateway lines providing the visibility that separates the layers.
This guide is the first sub-article of the SMS verification hub, and it shares the delivery-path logic with the AI verification fallback guide.
An OTP Crosses Four Layers Before the User Sees It
The first layer is the application: the platform decides to send a code and calls the messaging layer. The second is the gateway: it queues, routes, and submits the message through a SIM.
The third is the carrier network: it accepts, filters, and delivers the message. The fourth is the handset: the user's device, number, and settings decide whether the code is visible. Each layer has its own failure signals, and the gateway's logs provide the visibility that separates the layers.
The Failure Table Maps Symptom to Layer
| Symptom | Likely layer | First check |
|---|---|---|
| No code arrives, even at home | Application or bank risk | Trigger flow and risk rules |
| Code arrives hours later | Carrier or route | DLR latency and route quality |
| Codes stop from one sender | Carrier filter | Sender registration and short codes |
| Codes fail only abroad | Carrier or handset | Roaming, Wi-Fi Calling, number state |
| Codes arrive on another device | Application or handset | Registered number and device settings |
An example makes the mapping concrete: a bank user in a new country reports no code; the application log shows the request, the gateway shows acceptance, the SIM shows healthy, and the carrier DLR shows a risk-engine hold. The verdict is carrier-side, and the fix is a travel notice or a registered-device approval, not a new SIM.
Carrier Filters and Short-Code Behavior Differ by Market
Carriers filter on content, sender reputation, and traffic patterns, and short-code behavior varies by market and provider. A code that passes in one country can be blocked in another, and a sender ID that works for marketing may be filtered for verification traffic. The fix is sender registration per market and testing with the actual sender, not assuming the route behaves the same everywhere.
The filter test should be run per market with the actual sender: send a real code to a test number and check the DLR status and latency. The test result becomes the baseline for that market, and any change from baseline is the next incident's first clue.
The baseline should be recorded per market and per template, because a code that normally delivers in two seconds and now takes twenty is a route problem even when the final status says delivered.
Device and App Settings Add a Final Layer of Failure
The handset layer hides failures that look like carrier problems: a number with a stale SIM, a device that blocks the sender, or an app that filters the message. For travel users, the number's roaming state and Wi-Fi Calling configuration matter, as covered in the receive home SMS abroad guide. The fix is number validation and device-level checks.
The handset checks should be part of the support script, because a user who cannot explain their settings needs a guided path rather than a diagnosis. The script should cover airplane mode, Wi-Fi Calling, and the registered number.
Fix the Layers in the Right Order
The fix order follows the failure table: confirm the application requested the code, check the gateway queue and SIM health, verify the carrier route and sender registration, then look at the handset. Fixing the carrier before the SIM, or the content before the number, wastes the peak window. The order should be documented as a runbook so the on-call team follows the same path every time.
The order also applies to prevention: registration per market, fleet health checks, and number validation prevent the failures that the runbook diagnoses. The runbook and the prevention checklist should be reviewed together, because a team that prevents well has less to diagnose.
| Layer | Verdict question | Evidence |
|---|---|---|
| Application | Was the code requested? | Request log |
| Gateway | Was it accepted and queued? | Message ID and queue state |
| Carrier | What did the DLR say? | Status and latency |
| Handset | Is the number and device ready? | Number and device state |
The Troubleshooting Runbook
The runbook has five steps: check the application log for the request, check the gateway for acceptance and queue state, check the SIM fleet for health and rotation, check the carrier for DLR status and filters, and check the number and device for the user's state. Each step produces a verdict that rules a layer in or out, and the verdicts are logged so repeat failures become patterns.
An example runbook entry: a user reports no code; the application log shows the request, the gateway shows acceptance and no queue delay, the SIM shows healthy, the carrier DLR shows a filter rejection, and the number is valid. The verdict points to carrier-side filtering, and the fix is sender registration, not a content rewrite.
The runbook should also name the escalation: when the on-call team cannot clear the failure, the ticket moves to the carrier or the platform team with the layer verdicts attached. Escalation without evidence repeats the investigation.
The runbook should be exercised, not just written: run a monthly drill that replays a real past incident and measures how fast the team reaches the right layer. A runbook that has never been run is a theory.
The same runbook discipline applies to the verification architecture in the SMS verification hub, and the channel-level decision is covered in the SMS vs authenticator app guide.
Telarvo Expert Views
Nine out of ten OTP tickets are fixed in the wrong layer. We tell teams to run the runbook in order: application, gateway, carrier, handset. The delivery report is the map, and the SIM health is the first suspect, because a silent SIM looks like a carrier problem.
— Messaging Operations Engineer, Telarvo Store
Validation note: DLR semantics, carrier filters, and device behavior vary by market; validate per provider and device.
Conclusion
OTP troubleshooting works when the four layers are separated, the failure table maps symptoms to layers, and the runbook fixes them in order instead of guessing.
Key Takeaways for Support Teams
Separate application, gateway, carrier, and handset layers. Map every symptom to a layer before acting. Register senders per market and test with the actual sender. Document the runbook and log verdicts. Validate the number and device state for travel users.
Questions to Ask Before You Build the Runbook
Ask which failure signals each layer produces, how DLR labels map in your markets, and how SIM health is surfaced. Ask Telarvo Store for the gateway configuration that gives you the visibility the runbook needs.
FAQs
Why do codes fail even with a good gateway?
Because the failure can sit in the application, carrier, or handset layer, and the gateway cannot fix what it cannot see. The runbook exists to rule each layer in or out in order, and it should be exercised with a monthly drill.
What is the first thing to check?
Whether the application actually requested the code, then the gateway queue and SIM health, in that order, because fixing a lower layer first wastes the peak window and repeats the investigation.
Do carrier filters differ by market?
Yes, so sender registration and short-code behavior must be validated per country with the actual sender, and the baseline should be recorded per market and template.
Why do codes fail only when traveling?
The handset's roaming state and Wi-Fi Calling configuration change the delivery path, so validate the number's state abroad, add the market's sender registration to the checklist, and record a per-market delivery baseline.
What should the runbook log?
Each layer's verdict with its evidence, so repeat failures become patterns instead of repeat investigations, and the escalation moves with the evidence attached rather than restarting the diagnosis.