OTP SMS not arriving? How to debug one attempt, step by step
Robase · 2026-10-08
"I never got the code" is one of the most common support tickets an auth team sees. It is also one of the easiest to get wrong, because it sounds like one problem and is really several.
The fix starts with a habit: debug the attempt, not the account. Find the one send the user is talking about, read what happened to it, and work out which step failed. A request that was refused, a message that was sent but never confirmed, and a code that arrived after it expired all look the same to the user. They need different fixes.
This guide walks one OTP attempt from the number the user typed to the code they entered, using the statuses and errors in the Robase docs. Most of the steps apply to any SMS provider.
Start with the otp_id and its timeline
When your backend calls POST /v1/otp/send, Robase returns an id. Store it against the user and the login attempt. Never store the code itself; Robase never returns it (OTP verification).
With that id, GET /v1/otp/{id} returns the current status and a timeline of hops, oldest first (Delivery timeline). This is what you paste into the ticket.
| Timeline hop | What it means | | ------------ | ----------------------------------------------------------------------- | | queued | Stored, charged, waiting for the worker. status reads pending here. | | sent | Robase sent it to the network. | | delivered | The carrier sent a delivery receipt. | | failed | Robase could not send it, or the network reported it undelivered. | | verified | The user entered the right code. | | expired | The TTL ran out. |
A failed hop carries a reason token and a refunded flag. If you prefer push to polling, the otp.sent, otp.delivered, otp.verified, otp.expired and otp.failed webhooks carry the same story (Webhooks).
If the send call never returned an id, the attempt failed before anything left your system. That is where we start.
Step 1: Was the number valid E.164?
Robase accepts E.164 only: +2348012345678. No spaces, and no leading 0 without a country code. Anything else returns 400 with error.type: invalid_phone (SMS overview, Errors).
Nigerian users usually type the local format, 08012345678. Some type +234 0801... with the trunk zero left in. Normalize in your app before you call the API:
// Normalize a Nigerian phone number to E.164 before POST /v1/otp/send.
// Returns null when the input cannot be a Nigerian mobile number.
function toE164NG(input) {
let n = String(input).replace(/[\s().-]/g, '');
if (n.startsWith('+')) n = n.slice(1);
if (n.startsWith('2340')) n = '234' + n.slice(4); // +234 0801... typed with the trunk zero
if (n.startsWith('0')) n = '234' + n.slice(1); // local format 0801...
if (!/^234\d{10}$/.test(n)) return null; // +234 plus 10 digits
return '+' + n;
}
If the function returns null, ask the user to check the number. Do not send and hope. Show the normalized number back on the code entry screen ("We sent a code to +234 801 234 5678") so a typo is visible before the user waits.
Step 2: Is the destination supported and priced?
The country is read from the number. If Robase has no route for it, the send returns 400 country_not_supported (Multi-country).
Robase prices eight markets: Nigeria, Ghana, Kenya, South Africa, the United Kingdom, Benin, Ivory Coast and the United States. The live table is public at GET https://api.robase.dev/v1/pricing and on Pricing. In Nigeria the rate depends on the recipient's network: a number on Glo costs 3 credits (₦18), and one on any other listed network, MTN and Airtel included, costs 1 credit (₦6) (Pricing docs).
Robase also keeps a per-workspace country list on the Countries settings page in the dashboard. Today a send to a country that is off is logged and still sent. Once enforcement starts, it will be refused with 403 country_not_enabled (Rate limits). If you add users in a new country, check that list.
Step 3: Route and network
You do not pick the route. Robase picks an upstream for the destination country, and your application never sees which one (Routing and failover). What you can see is the outcome: the status, the timeline, and the reason token.
Two documented controls work at the level of a number range, and both can look like "OTP is broken for some users":
- Per-prefix volume.
POST /v1/otp/sendis counted per destination prefix, the first six digits of the E.164 number. The default is 300 OTPs per prefix per hour per workspace. - SMS pumping protection. A prefix with unusual traffic and a low verify rate can be throttled for an hour, and if it is flagged again within a day it is blocked for your workspace. Sends to it return
403 prefix_blockeduntil support lifts the block (Rate limits).
If one user fails, look at the number. If everyone on one prefix fails, look at these controls first, then at the network (see the last section).
Step 4: Sender ID and DND
OTP goes out under Robase sender names after your first top-up, so you don't need your own Sender ID for OTP. Robase is the default, and RAlerts is the other registered name. New workspaces send transactional SMS under their own approved Sender ID. Without one, POST /v1/sms/send to a country that offers custom Sender IDs returns 422 sender_id_required and charges nothing. Existing workspaces keep their current setup. Custom Sender ID requests are open in Nigeria, Ghana, Kenya, Uganda, Tanzania, South Africa, Côte d'Ivoire and Benin, from the Sender IDs page in the dashboard, after at least one successful credit purchase. Approval usually takes 1 to 4 weeks, and the networks set the pace (Sender IDs).
There is no sender ID field on the send endpoints. POST /v1/otp/send sends as the workspace default. So if a custom name is still pending, keep the default on a platform name so codes keep flowing.
On DND: Robase sends OTP and transactional SMS on transactional paths, so Nigeria's NCC Do Not Disturb registry is not treated as a promo filter for one-time passcodes (DND compliance). Robase does not publish a delivery percentage to DND numbers. For the longer version, see Nigeria SMS Sender ID for OTP.
Step 5: Was there enough credit in the wallet?
Robase is prepaid. If the balance is below the cost of the send, the request returns 402 with error.type: insufficient_credits, and nothing is sent (Errors). This is a real cause of "the code never came", and it tends to hit everyone at once, often at night.
Catch the 402 in your send path and show a clear message instead of a generic error. Then make sure you hear about the balance before it gets there: the credit_balance.low and credit_balance.exhausted webhooks fire as the balance drops, and credit_balance.topped_up confirms recovery (Webhooks). See monitor your SMS credit balance for the setup.
Step 6: Anti-spam and account state
A few documented outcomes come from Robase's anti-spam controls or the workspace's standing, not from the network (Errors):
| What you get | Meaning | What to do | | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | ---------------------------------------- | | 403 account_suspended | The workspace is suspended after antispam review. Nothing is charged. | Do not retry. Contact support to appeal. | | 403 account_temporarily_restricted | A 48h antispam pause. | Do not retry sends until it lifts. | | 403 content_blocked | POST /v1/sms/send from a new workspace, and the body reads as non-transactional. Not sent, not charged. | Send only transactional content. | | 503 screening_unavailable | POST /v1/sms/send from a new workspace, and the content check failed. Not sent, not charged. | Retry after the Retry-After header. |
content_blocked and screening_unavailable apply to POST /v1/sms/send. If you use POST /v1/otp/send, Robase composes the OTP body for you, so they only matter if you build your own code messages on the transactional SMS endpoint.
The state can also change after a send was accepted. If the workspace is suspended, or enters the 48h pause, before the OTP goes out, the OTP ends failed with reason workspace_suspended or workspace_restricted, it is not sent, and the charge is refunded (Delivery timeline). On transactional SMS the same reasons appear on a blocked hop, and an anti-spam stop shows blocked with antispam_blocked.
Step 7: Sent, delivered, or failed?
If the send was accepted, the timeline tells you how far it got.
failedwithsend_failed: Robase could not send the message.failedwithdelivery_failed: the network reported the message as failed, rejected, or expired.- a
senthop and nodeliveredhop: the message left Robase and no receipt came back.
That last case needs care. For an OTP, delivery is never the status; the status goes from sent to verified, expired or failed. Delivery shows up as a delivered hop on the timeline, a delivered_at time on GET /v1/otp/{id}, and the otp.delivered webhook, and only when the carrier sends a receipt (Delivery timeline, Webhooks). Some routes never send one, so an OTP with no delivered hop can still have reached the phone. A missing receipt is not proof of a missing SMS. Check whether the user went on to verify, and ask whether they have a code from a few minutes ago.
On credits: a send is charged when it is accepted (SMS overview). Only a terminal failed hop carries a refunded flag, read from the credit ledger. send_failed, delivery_failed, workspace_suspended and workspace_restricted failures are refunded; the one documented exception is max_attempts_exceeded (Step 9), which is not (Delivery timeline).
Step 8: Did the code expire first?
The default ttl_seconds is 600 (ten minutes), and you can set 1 to 3600 on the send (OTP verification). When it runs out, the timeline shows expired and a verify returns 409 otp_expired.
Compare the sent hop, the delivered hop or delivered_at if there is one, and the moment the user typed the code. If the message landed late, the user did nothing wrong. A TTL that is too short for a slow route turns a delay into a failure.
Step 9: Did verification fail, not delivery?
Sometimes the code arrived and the problem is on the verify side (OTP verification):
- A wrong code with attempts left is not an error:
200withvalid: falseandattempts_remaining. - Too many wrong codes:
409 max_attempts_exceeded. The timeline showsfailedwith reasonmax_attempts_exceeded, and that charge is not refunded, because the message was delivered. - Already used:
409 otp_already_verified.
A classic cause is resends. Every send creates a new OTP with its own id and its own code, and an earlier code stays valid against its own otp_id until it expires or runs out of attempts. Verify checks the code against the otp_id your app sends, so an older code can only verify if your app still sends the older id. Store the otp_id from each send and replace it on every resend, so your app always verifies against the newest one. Then ask users to enter the code from the most recent message: an older code typed against the newest id returns valid: false and uses one of that OTP's attempts.
Step 10: Resend timing and limits
Resends are where a small delay becomes a bad experience and a bigger bill. Robase allows 3 OTP sends per 10 minutes per phone number per workspace (Rate limits). Past that, you get 429 rate_limited with a Retry-After header in whole seconds. Honour it; do not loop.
Each resend is a new send and a new charge at the destination rate. A sensible pattern:
- Show a countdown before the resend button is enabled.
- Lengthen the wait after each resend.
- Cap resends per number well inside Robase's limit.
- Use an
Idempotency-Keyon every POST so a network retry does not double-charge. The same key within 24 hours returns the original response (Idempotency). Official SDKs set one for you.
Step 11: Encoding and segments (usually not the issue)
OTP sends on Robase are single-segment templates, and you do not control the body (Segments and encoding). Encoding matters when you send your own text on POST /v1/sms/send: one character outside the GSM alphabet moves the whole message to UCS-2, which fits 70 characters per part instead of 160, and you are charged the country rate times segments. The limit is six segments. The sanitize_symbols setting is on by default and rewrites characters such as ₦ to NGN when that lowers the part count.
When it is everyone, not one user
If many users on one network stop receiving codes at the same time, stop debugging single attempts. Check your provider's status page, look at verify rates by number prefix, and slow your resend button down before users burn through credits tapping it. We wrote a separate playbook for that case: When MTN Nigeria SMS is delayed.
What to put in the support ticket
- The
otp_id, the normalized E.164 number, and the time of the attempt. - The send response, or the
error.typeif the send was refused. - The
timelinefromGET /v1/otp/{id}, including anyreasonandrefunded. - How many sends that number had in the last 10 minutes.
- Whether the user later verified, on this attempt or a newer one.
With those five things, most tickets answer themselves.
Try it on a real handset
Robase sends SMS OTP, WhatsApp OTP and transactional SMS on prepaid credits (1 credit = ₦6). A Nigerian SMS OTP starts at 1 credit (₦6), and a Nigerian WhatsApp OTP is 4 credits (₦24). Live rates per network are on Pricing. Creating an account is free, and your first successful top-up adds bonus credits, once per account.
Start with the SMS OTP API Nigeria guide. If your concern is whether the number still belongs to the right person, rather than whether the code arrived, see TIRMS and number checks in Nigeria.