How do I troubleshoot failed SMS sends when the API returns success?

If the API returns success but the SMS never arrives, the failure is usually happening after your request is accepted—for example in the carrier network, message filtering, routing, or recipient-device handling.

Here’s a practical troubleshooting checklist:

1) Confirm what “success” means

A common mistake is treating an API 200 OK or "success": true as “delivered.”
Check whether the response indicates:

• Accepted for processing vs.
• Delivered to handset

If the API supports it, look for:

• a message ID / SID
• a delivery status
• a delivery receipt (DLR) or webhook callback

2) Check message status updates

Use delivery status callbacks/webhooks or status polling and look for states like:

• queued
• sent
• delivered
• undelivered
• failed

If it stays at queued or sent, the issue may be with carrier routing or downstream delivery.

3) Verify the destination number

Make sure the phone number is:

• in E.164 format (+14155552671)
• correct country code
• not missing digits
• not on a blacklist or opt-out list

Also test with:

• another number on a different carrier
• a different device
• a different region/country

4) Inspect carrier and content filtering

Carriers may silently block or delay messages due to:

• suspicious links
• short codes/long codes not registered properly
• A2P/10DLC compliance issues
• high-volume bursts
• spam-like wording
• blocked sender ID

Try a very plain test message:

• “Test message from system”
• no links
• no emojis
• no special characters

5) Check sender configuration

Depending on your provider/country, delivery can fail if:

• the sender number isn’t provisioned for the destination country
• the sender type is not allowed for that message type
• the sending pool is misconfigured
• alphanumeric sender IDs aren’t supported in the target country

6) Review rate limits and throttling

The API may accept the request but providers/carriers may throttle later. Check:

• provider rate limits
• per-recipient frequency limits
• burst sending
• daily quotas
• duplicate message suppression

7) Examine provider logs and error codes

Look for:

• message-level status/error codes
• carrier rejection reasons
• webhook callbacks with undelivered or failed
• account-level alerts

Common causes include:

• invalid destination
• carrier unreachable
• blocked content
• unverified sender
• insufficient compliance registration

8) Confirm opt-in/opt-out behavior

If the recipient previously replied:

• STOP
• UNSUBSCRIBE
• CANCEL

they may be automatically opted out and messages won’t deliver.

9) Test with a minimal end-to-end setup

Send:

• a short plain-text message
• to a known good number
• from a known good sender
• during normal business hours
• with delivery receipts enabled

If that works, add complexity back gradually.

10) Compare with provider dashboard

Many SMS providers show more detail in their dashboard than the API response:

• delivered vs failed
• carrier response codes
• internal routing errors
• message trace
• webhook history

11) Check whether the recipient device is the issue

Delivery can fail or be delayed if:

• the device is off
• no signal / roaming issues
• SMS inbox is full
• device blocks unknown senders
• dual-SIM or messaging app issues

12) Escalate with provider support

If you have:

• message ID
• timestamp
• recipient number
• sender ID
• carrier response / status

support can often identify the exact point of failure.

---

Fast debugging sequence

1. Send a plain test SMS to a different number.
2. Verify the message ID and status callback.
3. Check provider logs for carrier rejection codes.
4. Confirm compliance/sender registration.
5. Compare accepted vs delivered status.

If you want, I can also give you a provider-agnostic SMS troubleshooting flowchart or a checklist tailored to Twilio / Vonage / AWS SNS / MessageBird.