OTP / Verification Codes Aren't Arriving

When OTP Codes Don't Land

OTPs are time-sensitive, so a delay feels like a failure. Most of the time it's one of a handful of causes — here's how to tell which.

First, check the delivery report

Open Portal > History and find the message. The status tells you a lot:

• DELIVERED — it reached the handset. If the user still can't see it, ask them to check spam/blocked-sender filters, or that the phone has signal.
• FAILED / REJECTED — the network refused it. Usually a wrong number format, a blocked Sender ID, or content the carrier filtered.
• PENDING / DISPATCHED — still in transit. Brief network congestion or the phone is off/out of coverage.

Common causes & fixes

• Wrong number format: Always send in international format — 2557XXXXXXXX. A leading 0 or + mismatch is the #1 cause.
• Out of credits: If your balance hit zero, sending pauses. Check Portal > Billing and top up.
• Sender ID not approved: If your Sender ID is still pending, codes may not go out. See "My Sender ID Was Rejected or Is Still Pending".
• Content filtering: Avoid links and money words in the OTP body — keep it to the code and your brand.
• Rate limits on your side: Sending many codes to the same number in seconds can trip anti-spam rules. Add a short cooldown and a resend limit.

Build OTP the reliable way

Use the Verify API rather than raw SMS sends — it handles channel fallback and expiry for you. See the developer docs at Portal > Developer.