Skip to content
Oxtro

Blog

OTP code not arriving? A troubleshooting guide for SMS and WhatsApp verification

When users say they never got the code, the cause is usually one of a handful of things. Work through them in this order, starting with your own logs, before you blame the provider.

Last updated

A phone waiting for a code while a wrench repairs a broken signal path from a cell tower.

Start with your own logs

Find the attempt for the user who complained and answer three questions:

  1. Did your server call the provider at all? A validation error, a CAPTCHA failure or your own rate limit may have stopped it first.
  2. What did the provider answer? An error code tells you far more than the user's report. Record it for every request.
  3. What happened after? Most providers report a delivery status, either in a webhook or by looking up the message. "Sent" means it left the provider, "delivered" means the phone or app confirmed it.

If you do not log the provider's response and delivery status today, start now. Every other step below depends on it.

The number is wrong

The most common cause by far.

  • Use E.164 format: a plus sign, the country code and the number, with no spaces or leading zero, as in +213555123456. A local format such as 0555 12 34 56 will fail or reach the wrong country.
  • Check the country. A form that assumes one default country breaks for everyone else. Let users pick their country, and validate the length for it. Our phone number formatter converts a whole list to E.164 and flags the invalid ones.
  • Check the line type. Some landlines and some virtual numbers cannot receive SMS. Offer a voice call for those.

The message was sent but did not arrive

Carrier filtering

Carriers filter business SMS they consider spam or unregistered. Codes are usually let through, but not always.

  • Keep the message short and plain: the code, your service name and how long it is valid.
  • Avoid links in verification messages. Shortened links in particular look like phishing.
  • Register your sender where the country requires it, such as 10DLC in the United States or DLT in India.

The phone cannot receive it

  • No signal, a full inbox on older phones, or a phone switched off.
  • Roaming abroad, where some carriers delay or drop international SMS.
  • The user blocked unknown senders or business messages in the phone's settings.

For these, the fix is a second channel. Offer a voice call or a WhatsApp message after 30 to 60 seconds.

Delays

A code that arrives after the user has given up looks like a code that never arrived. Show a countdown before the resend button, make the code valid for long enough, at least a few minutes, and say on screen where the code will come from.

The code arrived but will not verify

  • Expired. The user took longer than the validity window. Show the expiry time on screen and let them request a new code.
  • A newer code replaced it. Users who tap resend several times often type the first code they see, which is no longer valid. Tell them to use the latest message.
  • Too many attempts. After the attempt limit, the code stops working even if the next guess is right. Ask for a new code.
  • The wrong attempt was checked. If your server keeps the attempt identifier in the session, a user with two tabs open can check the code against the other one.
  • Autofill filled something else. On the web, add autocomplete="one-time-code" to the code field so iOS and macOS suggest the right value.

Rate limits and cooldowns

Limits protect you from abuse, but they also block real users who are impatient.

  • A resend cooldown, typically 30 to 60 seconds, stops repeated taps from sending many codes.
  • Per-phone limits per hour and per day stop one number from being flooded.
  • Per-IP and per-account limits on your side stop bots.

When a limit is hit, tell the user when they can try again instead of showing a generic error.

WhatsApp codes

When codes are sent on WhatsApp, a few causes are specific to it:

  • The number is not on WhatsApp. Not everyone uses it. Fall back to SMS or email.
  • The sending number is offline. When codes are sent from your own linked WhatsApp number, as with Oxtro, the phone that owns it has to stay active. WhatsApp logs out linked devices when the main phone has not been used for some time.
  • The message is in the wrong chat. Users may look for an SMS. Say on screen that the code was sent on WhatsApp, and from which name.

With Oxtro, each case has its own error code:

ErrorMeaningWhat to do
CONNECTION_OFFLINEThe linked number is disconnectedRelink the number, and fall back to another channel meanwhile
OTP_COOLDOWN_ACTIVEA code was sent to this phone moments agoWait details.retry_after_seconds
RATE_LIMITEDThe hourly or daily cap for this phone is reachedAsk the user to try later
OTP_INVALIDThe code is wrongLet the user try again
OTP_EXPIREDThe code is no longer validSend a new code
OTP_MAX_ATTEMPTSToo many wrong guessesSend a new code

The OTP API reference lists every error, and the webhooks guide shows how to be told when a number disconnects.

When the problem is fraud: SMS pumping

Sometimes the problem is not that codes fail, but that too many are sent. Watch for:

  • a sudden rise in verification spend with no rise in completed sign-ups;
  • requests to countries you do not normally serve;
  • many requests to numbers that differ only in the last few digits;
  • verifications that are started but almost never completed.

These are signs of SMS pumping: bots request codes to numbers that earn their owners a share of what you pay. To stop it, block countries you do not serve, add a CAPTCHA or bot check before the code is requested, cap requests per IP address and per number range, and turn on your provider's fraud protection. Codes sent on WhatsApp are not routed through premium-rate phone numbers, which removes the incentive for this particular attack.

A checklist for the code screen

  • Numbers stored and sent in E.164 format
  • The provider's response and delivery status logged for every attempt
  • A visible countdown before resend, and a clear expiry time
  • A second channel after 30 to 60 seconds
  • autocomplete="one-time-code" on the input
  • Friendly messages for every limit, with a time to retry
  • Alerts on spend and on completion rate, to catch fraud early

Choosing a provider is the other half of reliable verification. Read how to choose an SMS service for two-factor authentication.

Connect your first number today

Create a workspace, scan the QR code and send a message.

Create account