Diagnosing Twilio Messaging Failures: 'Failed' vs 'Undelivered' Statuses

The Delivery Gap: Sent vs. Delivered

A common point of failure in Twilio integrations is relying on the initial API response to confirm message delivery. When you send a message via the API, a 201 Created response only confirms that Twilio has accepted the request. It does not guarantee the recipient will see the message.

To determine if a message actually reached the device, you must monitor the Status Callback—a webhook Twilio sends to your server as the message moves through the carrier network. The most critical distinction for debugging is the difference between a Failed status and an Undelivered status.

Status Diagnostic Table

Status	Primary Cause	Typical Origin	Key Indicator
Failed	Request error or invalid destination	Twilio / API Level	Invalid number format, blocked sender
Undelivered	Carrier rejection or device issue	Carrier / Recipient Level	Spam filtering, inactive SIM, landline

Step-by-Step Delivery Troubleshooting

Follow these checks in order to isolate whether the issue lies in your configuration, Twilio's platform, or the recipient's carrier.

1. Verify Status Callback Connectivity

If your application never receives a status update, you cannot diagnose the failure. Check the Twilio Debugger in the Console to see if Twilio is receiving 4xx or 5xx errors when attempting to hit your webhook URL.

• Check: Ensure your endpoint is publicly accessible and handles POST requests.
• Risk: If your server returns a non-200 response, Twilio will log a webhook failure, but the message may have still been delivered.

2. Analyze the Error Code

When a status is Failed or Undelivered, Twilio attaches a specific error code to the callback. Use the following logic to determine the fix:

• Error 30003 (Unreachable Destination): The number is likely a landline or an inactive account. Use the Twilio Lookup API to verify the line_type_intelligence of the destination number before sending.
• Error 30007 (Carrier Filtering): The carrier has flagged the content as spam. This is common when sending identical messages to many users or using a Long Code for high-volume traffic.
• Invalid 'From' Number: Ensure you are using a supported sender type for the destination country. Using a US Long Code to send to certain international regions often results in silent drops or immediate Failed statuses.

3. Test Content and Volume

If you see Undelivered statuses with carrier filtering codes, test the message content by changing the wording. Avoid using shortened URLs (like bit.ly) or excessive capitalization, as these trigger automated carrier filters.

Implementation Example: Lookup Verification

To prevent 30003 errors, implement a lookup check before triggering the message. This reduces wasted spend and improves delivery rates.

# Example using Twilio Python Helper Library
# Required permissions: Account SID and Auth Token with API access
from twilio.rest import Client

client = Client('AC_ACCOUNT_SID', 'AUTH_TOKEN')

# Check if the number is SMS capable
phone_number = client.lookups
    .v2
    .phone_numbers('+15550001111')
    .fetch(fields='line_type_intelligence')

if phone_number.line_type_intelligence['type'] != 'mobile':
    print("Warning: Destination is not a mobile device. SMS may fail.")
else:
    # Proceed to send message
    pass

Verification and Limitations

To verify the fix, send a test message to a known-working mobile device and monitor the Programmable Messaging Logs in the Twilio Console. Confirm that the status transitions from Accepted → Sent → Delivered.

Limitations: Carrier filtering is managed by the telecom provider, not Twilio. Even with a verified sender, carriers may block messages based on their own internal heuristics. There is no API setting to "force" delivery through a carrier filter.

Escalation Criteria

Contact Twilio Support if you encounter the following conditions:

• A high percentage of Undelivered messages to a single carrier despite low volume and varied content.
• Messages are marked as Delivered in the logs, but the end-user consistently reports they were not received (indicating a potential "silent drop").
• Consistent 5xx errors in the Twilio Debugger for your status callbacks despite your server being healthy.