Twilio's undelivered status means the carrier accepted the message (so it progressed past sent) but could not deliver it to the destination handset, returning a delivery failure receipt to Twilio. The error code on the undelivered message in the Console tells you exactly which of the twelve possible failure categories applies, and each category has a distinct fix. This checklist covers all twelve in order from most to least common, so you can find your specific cause in under 3 minutes.
The Twelve Causes in Order of Likelihood
Cause 1 (most common): error code 30003, Unreachable Destination Handset, means the recipient's phone is off, out of coverage, or has a full message inbox: the message will be retried by the carrier until the validity period expires. Cause 2: error code 30004, Message Blocked, means the recipient's carrier blocked the message for policy reasons, often because the recipient previously opted out of messages from this number's campaign: check your opt-out list and do not send to opted-out numbers. Cause 3: error code 30005, Unknown Destination Handset, means the number is not registered with any carrier in its home country: verify the number is active using the Lookup API. Cause 4: error code 30006, Landline or Unreachable Carrier, means the destination number is a landline or a VoIP number that cannot receive SMS: use the Lookup API's line_type_intelligence feature to detect landlines before sending. Cause 5: error code 30007, Carrier Violation, means your message content, sending pattern, or registration status triggered a carrier compliance block: review your 10DLC registration and message content. Cause 6: error code 30008, Unknown Error, is returned by some carriers as a catch-all: investigate by testing the same content to a different carrier's number to isolate whether the issue is content or carrier-specific.
The Remaining Six Causes
Cause 7: error code 21610, Attempt to Send to Unsubscribed Recipient, means the destination number has been added to your Twilio account's opt-out registry via a STOP reply to a previous message: remove opted-out numbers from your send list and never retry sends to opted-out numbers. Cause 8: error code 30034, Message Blocked Due to SHAFT Content, means your message contains content related to Sex, Hate, Alcohol, Firearms, or Tobacco, which carriers systematically block: revise the message content to remove the SHAFT keyword that triggered the filter. Cause 9: error code 30450, Message Blocked for Not Being Registered, means your 10DLC Campaign is not yet approved or the sending number is not linked to an approved campaign: confirm your Campaign SID and number assignment in the Console under Messaging, then Regulatory Compliance. Cause 10: error code 11751, MMS Media Exceeds Size Limit, means a media attachment on an MMS message exceeded the 5MB size limit for media content: compress or resize the attachment and resend. Cause 11: no error code, permanent sent status, means silent carrier filtering with no delivery receipt returned: test with different content and a different carrier recipient to isolate. Cause 12: error code 30401 or 30451, means the destination number is in a country that your Twilio account has not enabled for outbound messaging: enable the country under Console, then Settings, then Messaging Geographic Permissions.
How to Isolate the Specific Cause
Open the failed message in the Console under Monitor, then Logs, then Messages and find the ErrorCode field: if an error code is present, use it to identify which of the twelve causes applies and apply the specific fix for that code as described above. If the ErrorCode field is empty and the status is undelivered, the message experienced silent carrier filtering: send a plain text message with no links or special characters to a test number on the same carrier and compare the delivery result to isolate whether the issue is in the message content or the carrier route. To determine the destination carrier, use the Twilio Lookup API endpoint for the recipient's number with the type=carrier parameter: the response includes the carrier name, which you can use to check Twilio's carrier status page for known delivery issues with that carrier. Test a small batch of messages to 5 different recipient numbers across different carriers and compare which ones deliver successfully: if all T-Mobile recipients fail while AT&T and Verizon recipients succeed, the issue is with the T-Mobile carrier route for your sending number, which requires a Twilio support ticket.
When to Escalate
Escalate to Twilio support when error code 30007 is appearing on messages that comply with your approved 10DLC Campaign's use case and message content, have verified opt-in documentation, and are being sent within normal throughput limits: this combination suggests a carrier-side routing change that Twilio's network team can investigate by providing your Campaign SID and a sample of affected Message SIDs. File a support ticket for widespread 30004 (blocked) errors that started suddenly without any change to your content or sending patterns, as this can indicate a carrier policy change or a spam complaint wave that triggered a temporary block on your sending number, which requires carrier-level remediation. Seek specialist help when undelivered rates for a specific destination country suddenly increase from a baseline of under 5 percent to over 20 percent: international carrier route changes happen without notice and require carrier routing investigation by Twilio's network connectivity team. Always include in your support ticket: the affected Message SIDs, the From number, the approximate number of failed messages, the time window, the error code (or confirmation that there is no error code), and your 10DLC Brand SID and Campaign SID.
Conclusion
Every undelivered Twilio message has a specific cause identifiable by its error code, and each error code has a targeted fix: working through this checklist in order saves the hours spent making broad changes that do not address the actual failure point. If your messages are showing undelivered and you need help identifying the specific cause, contact our team and we will diagnose and fix it within the hour.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.