SMS Delivery Error Codes: A Plain-English Reference

If you've landed here, chances are you're troubleshooting an SMS delivery issue — an error code, a failed message, or a confusing "sent but not delivered" status.

At FranFunnel, we work with franchise brands and multi-location businesses that send millions of text messages every year across lead follow-up, qualification, booking, and re-engagement. Deliverability isn't an afterthought for us — it's core to the product.

This guide is a plain-English reference to the most common SMS delivery error codes: what they usually mean, why they happen, and what to do next (or when not to do anything at all).

Important: Many delivery errors are outside your control. Mobile carriers ultimately decide whether a message is delivered.

Account / Auth Errors

20003 — Authentication Failed

What it means The API request couldn't be authenticated — the credentials used to send the message were invalid or missing.

Common causes

• Incorrect Account SID or Auth Token in your integration
• API keys were rotated or revoked without updating your system
• Request is being made against the wrong Twilio subaccount

What to do next

• Verify your Account SID and Auth Token in the Twilio console
• Regenerate your Auth Token if you suspect it was compromised, then update it in every integration
• Check that you're using credentials for the correct account or subaccount

20429 — Too Many Requests (Rate Limited)

What it means Your account has exceeded the allowed request rate for the Twilio API — too many messages submitted in too short a window.

Common causes

• A bulk send or trigger fired more requests per second than your account tier allows
• A retry loop without backoff re-hammering the API after failures
• Multiple systems sending simultaneously through the same account

What to do next

• Implement exponential backoff and retry logic for rate-limited requests
• Throttle bulk sends to stay within your account's messages-per-second limit
• Contact Twilio support to request a higher throughput limit if your volume requires it

20500 — Internal Server Error

What it means Twilio's servers returned an unexpected error — this is on their side, not yours.

Common causes

• Temporary service disruption or platform instability on Twilio's end
• An edge case in the request that triggered an unhandled error

What to do next

• Check the Twilio Status Page for any active incidents
• Retry the message after a short delay using exponential backoff
• If the error persists, open a support ticket with Twilio

20503 — Service Unavailable

What it means Twilio's messaging service is temporarily unavailable — typically due to high load or a planned maintenance window.

Common causes

• Twilio platform maintenance or degraded service
• Upstream carrier outages affecting message routing

What to do next

• Check the Twilio Status Page for active incidents
• Queue and retry failed messages once the service is restored
• Set up monitoring on Twilio's status feed to receive alerts automatically

Messaging / Number Errors

21211 — Invalid 'To' Phone Number

What it means The destination phone number is not a valid phone number format — it can't be parsed or routed.

Common causes

• Number formatted incorrectly (missing country code, wrong number of digits, contains letters)
• Number was entered by a lead with a typo
• Empty or null value passed as the 'To' parameter

What to do next

• Validate all numbers to E.164 format (+1XXXXXXXXXX) before attempting to send
• Use Twilio Lookup to validate numbers before they enter your send queue
• Flag and exclude invalid numbers from automated sequences

21268 — Sending to Premium Rate or Information Service Number Not Allowed

What it means Twilio does not allow SMS messages to be sent to premium rate or information service numbers. These are higher-cost numbers associated with special services — think 900-number style lines or paid information hotlines. Twilio's Lookup API classifies these as premium line type.

Common causes

• The 'To' number is a premium rate or information service number, which Twilio explicitly blocks as an SMS destination
• Your application accepted a destination number without validating its line type first
• Your application allows user-entered or international numbers, which can expose your account to premium-rate fraud attempts in high-risk geographies

What to do next

• Validate destination numbers before sending using GET /v2/PhoneNumbers/{PhoneNumber} with Fields=line_type_intelligence — reject any number where line_type_intelligence.type is premium
• If your application allows broad international sending, review your SMS Geographic Permissions in the Twilio console and block countries you don't intend to message
• Send to a standard SMS-capable number only — there is no workaround for premium-rate destinations

21408 — Permission Not Granted for Region

What it means SMS messaging is not enabled for the destination country on your Twilio account — your geographic permissions don't include the recipient's region.

Common causes

• The lead's phone number is from a country your account hasn't explicitly enabled
• Geographic permissions were not set up when the account was configured
• A lead entered an international number on a form that didn't validate country

What to do next

• In the Twilio console, go to Messaging > Settings > Geo Permissions and enable the required countries
• If you only send domestically, add validation to block non-US/CA numbers at intake
• Review whether international messaging is actually needed for your use case before enabling additional regions

21602 — Message Body Is Required

What it means The API request was sent without a message body — the 'Body' parameter was empty or missing.

Common causes

• A template variable failed to resolve, producing an empty string
• A conditional logic error in your message builder resulted in no content being passed
• The Body field was accidentally omitted from the API call

What to do next

• Add server-side validation to reject sends where the message body is empty before hitting the API
• Review template logic for any variables that could evaluate to null or empty
• Log outbound message content before sending to catch empty-body conditions

21604 — 'To' Phone Number Is Required

What it means The API request was sent without a destination number — the 'To' parameter was empty or missing entirely.

Common causes

• A lead record didn't have a phone number when the send was triggered
• A mapping error in your CRM integration passed a null value for the phone field
• A workflow fired before the phone number was collected

What to do next

• Validate that a phone number exists before triggering any outbound message
• Add a guard in your automation workflow to skip or hold sends where 'To' is empty
• Check your CRM field mappings to ensure the phone number is being passed correctly

21606 — 'From' Number Is Not a Valid SMS-Capable Number

What it means The sender number specified in the 'From' parameter is not provisioned for SMS on your Twilio account, or isn't SMS-capable.

Common causes

• A voice-only number was used as the sender
• The 'From' number was released or de-provisioned but is still referenced in your config
• A typo or misconfiguration in the sender number setting

What to do next

• Verify the 'From' number in your Twilio console under Phone Numbers > Manage
• Confirm the number has SMS capability enabled
• Update your configuration to use a valid, SMS-capable sender number

21610 — Attempt to Send to Unsubscribed Recipient

What it means The destination number has opted out of messages from your sender — they previously replied STOP and the number is on your opt-out list.

Common causes

• A contact replied STOP and was not removed from your active send lists
• An old contact was re-imported into a campaign without checking opt-out status
• Opt-out records weren't synced between Twilio and your CRM

What to do next

• Honor opt-outs immediately — do not attempt to work around this error
• Sync Twilio's opt-out list with your CRM regularly so unsubscribes suppress across all systems
• Never re-subscribe a number that opted out without explicit re-consent from the recipient

21612 — 'To' Phone Number Is Not Currently Reachable

What it means The destination number is valid but temporarily unreachable — the handset may be off, out of range, or the number is being ported.

Common causes

• Phone is powered off or out of coverage at time of send
• Number is mid-port between carriers
• The recipient's plan has been suspended

What to do next

• Retry the message after a delay — many temporary reachability issues resolve within hours
• If repeated retries fail across days, treat the number as inactive
• Do not retry indefinitely; set a maximum attempt limit

21614 — 'To' Number Is Not a Valid Mobile Number

What it means The destination number is not classified as a mobile number — it's likely a landline, VoIP line, or other non-SMS-capable number type.

Common causes

• Lead entered a work or home landline on the inquiry form
• A VoIP or internet phone number was submitted
• Number lookup wasn't performed before adding to an SMS sequence

What to do next

• Use Twilio Lookup with line type intelligence at the point of form submission to identify non-mobile numbers
• Route landline leads to email or phone-call sequences instead of SMS
• Flag and segment non-mobile numbers to prevent repeated failed send attempts

21617 — Message Concatenation Limit Exceeded

What it means The message body exceeds the maximum allowed length for concatenated SMS segments — the message is too long to send.

Common causes

• A long template with several variables that resolve to lengthy strings
• Unicode characters (emoji, special characters) that reduce the per-segment character count from 160 to 70
• No character limit enforced in the message builder

What to do next

• Keep SMS messages concise — aim for 160 characters or under per segment
• Test templates with the longest likely variable values to check final length
• Remove emoji or non-ASCII characters if character count is close to the limit

21635 — Landline or Unreachable Carrier

What it means The number resolves to a landline or is served by a carrier that cannot receive SMS messages.

Common causes

• Lead submitted a home or office landline number
• Number belongs to a small or regional carrier without SMS interoperability
• VoIP number that doesn't support inbound SMS

What to do next

• Add number type validation at lead intake using Twilio Lookup
• Create a fallback workflow for landline numbers (email, call queue)
• Do not retry SMS to confirmed landlines

21659 — Destination Number Blocked (Toll-Free)

What it means The destination number has been blocked from receiving messages sent from toll-free numbers — either by the carrier or by the recipient.

Common causes

• The recipient's carrier blocks toll-free SMS by default
• The recipient previously reported messages from a toll-free sender as spam
• Toll-free messaging is restricted in the destination region

What to do next

• Consider using a 10DLC registered long code as your primary sender for lead outreach
• Review whether your toll-free number has been flagged for spam — check your Twilio account for compliance notices
• Route leads in affected regions through a local long code sender

21660 — Mismatch Between 'From' Number and Account

What it means The sender specified in the 'From' parameter is not owned by the account or subaccount identified by the API credentials in the request. Twilio requires the 'From' sender to be hosted within Twilio and belong to the same account creating the message.

Common causes

• The request was authenticated with the wrong Account SID, Auth Token, or API Key — so the credentials point to a different account than the one that owns the sender number
• The 'From' phone number belongs to a different subaccount or to the parent account, not the one making the request
• The phone number was transferred between accounts or subaccounts and the application still uses the old credentials
• A 'From' number was included alongside a MessagingServiceSid, but the specified sender doesn't belong to the same account creating the message

What to do next

• Verify that your API credentials match the account or subaccount that owns the sender you're using — check in the Twilio console under Phone Numbers > Manage
• If sending from a subaccount, use that subaccount's credentials when creating the message, not the parent account's
• If the number was moved to a different subaccount, update your application to use the new account's credentials
• If you use MessagingServiceSid, omit the 'From' parameter entirely and let Twilio choose a sender from the Messaging Service's Sender Pool

Carrier Delivery Errors

11751 — Message Rate or Queue Limit Exceeded

What it means The message was rejected because your account's outbound message queue is full or you've hit a per-carrier rate limit.

Common causes

• A large bulk send overwhelmed the queue faster than messages could be delivered
• Per-carrier throughput limits were reached during a high-volume window
• Retry logic re-queued failed messages, compounding the backlog

What to do next

• Spread bulk sends over time using a throttled send queue
• Implement proper backoff on retries to avoid re-flooding the queue
• Monitor queue depth during large campaigns and pace sends accordingly

12300 — Message Rejected Before Sending

What it means The message was rejected by Twilio before it was ever submitted to the carrier — typically a content or validation issue caught upstream.

Common causes

• Message content triggered a pre-send content filter
• A required parameter was missing or malformed
• The request didn't conform to the messaging API specification

What to do next

• Review the full error response body for additional detail on why the message was rejected
• Check message content against Twilio's messaging guidelines
• Validate all required parameters before submitting

30003 — Unreachable Destination Handset

What it means The destination handset was unreachable when the carrier attempted delivery — the phone was off, out of coverage, or the number was inactive.

Common causes

• Phone is powered off or in airplane mode
• Recipient is in an area with no carrier signal
• The number is no longer active (disconnected or reassigned)

What to do next

• Retry once or twice with a delay — temporary outages resolve on their own
• If the error persists across multiple days, mark the number as inactive
• Remove persistently unreachable numbers from automated sequences to protect your sender reputation

30004 — Message Blocked by Carrier

What it means The carrier received the message but made a deliberate decision to block it before delivery to the handset.

Common causes

• Message content triggered the carrier's spam or compliance filters
• The sender number has a poor reputation or has been flagged for abuse
• The message matched patterns associated with high-risk or prohibited content categories (loans, sweepstakes, etc.)
• Your 10DLC campaign registration doesn't cover the use case in the message

What to do next

• Review your message content for anything that could trigger carrier filters: urgency language, all caps, excessive punctuation, promotional phrases
• Confirm your 10DLC brand and campaign registration is approved and matches the message type you're sending
• Check your sender reputation — if a number has been flagged, consider retiring it
• Never attempt to disguise blocked content — that accelerates filtering across all your senders

30005 — Unknown Destination Number

What it means The carrier doesn't recognize the destination number — it may be unallocated, out of service, or not routable on the carrier network.

Common causes

• Number was recently disconnected or is not yet active
• Number was never assigned to a subscriber
• A typo in the number results in an unallocated number

What to do next

• Validate numbers with Twilio Lookup before sending
• If a lead-submitted number returns 30005, follow up via another channel (email) to confirm their number
• Remove confirmed unknown numbers from send queues

30006 — Landline or Non-SMS Number

What it means The destination number is a landline or otherwise does not support SMS — the carrier confirmed it cannot receive text messages.

Common causes

• Franchise lead submitted a business landline as their contact number
• Number is a VoIP line without SMS capability
• Number lookup was not performed at intake

What to do next

• Segment landline contacts into a phone-call or email workflow
• Use Twilio Lookup at lead intake to catch landlines before they enter your SMS queue
• Do not retry — landlines will never receive SMS

30007 — Carrier Violation or Filtering

What it means The carrier filtered or rejected the message based on content, sender reputation, or compliance rules — similar to 30004 but applies more broadly across carrier-level filtering decisions.

Common causes

• Message content matched carrier spam or phishing detection patterns
• Sender is not registered for 10DLC or toll-free verification
• High complaint rate on the sending number or campaign
• Message volume spike that triggered anomaly detection

What to do next

• Ensure your 10DLC brand and campaign are registered and approved before sending at volume
• Review message content — avoid high-pressure language, excessive links, or URL shorteners
• Reduce sending velocity and monitor complaint rates
• If filtering persists despite clean content, contact Twilio support to investigate the sender's standing

30008 — Message Queued but Not Delivered

What it means The message was accepted and queued by the carrier but was never confirmed as delivered to the handset — the carrier returned an ambiguous status.

Common causes

• The handset came online after the carrier's delivery window expired
• Carrier-side delivery receipt timeout — the carrier stopped tracking the message
• Intermittent carrier network issues at the time of delivery attempt

What to do next

• Treat 30008 as a soft failure — do not count it as a definitive non-delivery
• Retry with a delay if the context warrants it (e.g., a critical lead follow-up)
• Monitor the rate of 30008 errors — a spike may indicate carrier network issues or sender reputation degradation

30017 — Carrier Network Error

What it means A network-level error occurred at the carrier during message routing — this is a carrier infrastructure issue, not a content or configuration problem.

Common causes

• Carrier network outage or degraded routing
• Inter-carrier handoff failure for messages crossing networks
• Temporary infrastructure issue in the recipient's region

What to do next

• Retry after a delay — carrier network errors are usually transient
• Check for any known carrier outages in the affected region
• If errors are sustained across a specific carrier or region, consider routing through an alternate sender

30018 — Delivery Timeout

What it means The message was not delivered within the carrier's allowed delivery window and was dropped.

Common causes

• Phone was offline for an extended period and the carrier stopped retrying
• Message TTL (time-to-live) was set too short
• High network congestion delayed delivery past the timeout threshold

What to do next

• Retry for high-priority messages if enough time has passed that the context is still relevant
• Do not retry time-sensitive messages (e.g., "your appointment is in 10 minutes") past their useful window
• Review your message TTL settings if you frequently see timeouts

30019 — Message Expired

What it means The message expired before it could be delivered — the TTL set on the message elapsed before the carrier could successfully route it.

Common causes

• TTL was configured too aggressively short
• Recipient was offline during the entire validity window
• Network congestion delayed routing long enough to exceed TTL

What to do next

• Increase message TTL for non-time-sensitive messages
• For time-sensitive messages, accept expiration as expected behavior rather than retrying stale content
• Consider whether the message is still relevant before retrying

30023 — Destination Blocked Messages

What it means The destination number has been configured to block incoming messages — either by the subscriber or their carrier plan.

Common causes

• Recipient has a messaging block set up with their carrier
• Number is enrolled in a robocall/spam blocking service that also blocks texts
• Corporate-issued devices configured to block unsolicited messages

What to do next

• Do not retry — blocked destinations will not become reachable by resending
• Mark the number as undeliverable and route the lead to another channel
• Consider reaching out via email if available

30024 — Message Failed Due to Destination Restrictions

What it means The recipient's number or plan has restrictions in place that prevented delivery — the carrier imposed a restriction specific to this destination.

Common causes

• Subscriber is on a plan that restricts certain message types
• Regional or regulatory restrictions in the destination area
• Number type restrictions (e.g., some prepaid plans limit inbound commercial messages)

What to do next

• Route leads with persistent 30024 errors to alternative follow-up channels
• Do not retry repeatedly — restrictions are typically persistent
• Log the error and flag the contact for manual outreach

30034 — Message Content Rejected

What it means The message content itself was explicitly rejected by the carrier — the text, links, or attachments violated carrier content policies.

Common causes

• Message contains prohibited content categories (adult content, illegal activity, etc.)
• A URL in the message resolved to a flagged or blocked domain
• Message matched patterns from known spam or phishing campaigns

What to do next

• Review and revise message content to comply with carrier guidelines
• Avoid URL shorteners — use full, branded domains or Twilio-hosted shortlinks
• Never send content in prohibited categories — repeated violations can result in number suspension
• If content appears clean, check whether the linked domain is on any carrier blocklists

30035 — Destination Carrier Rejected the Message

What it means The recipient's carrier made a final decision to reject the message — delivery will not be reattempted by the carrier.

Common causes

• Carrier-side anti-spam or compliance enforcement
• Sender number has accumulated complaints on the destination carrier's network
• Message content or volume patterns triggered carrier-level blocking

What to do next

• Treat 30035 as a hard failure on that carrier for that sender
• Review sender reputation on the affected carrier
• If the issue is widespread, rotate to a different sending number and investigate the root cause

30410 — Sender Not Authorized

What it means The sending number is not authorized to send to the destination — typically a carrier-level authorization issue related to registration or campaign approval.

Common causes

• 10DLC campaign not yet approved or not covering this message type
• Toll-free number not verified for commercial messaging
• Sender is registered for one use case but the message matches a different category

What to do next

• Verify your 10DLC brand and campaign registration status in the Twilio console
• Ensure the campaign use case matches the actual messages being sent
• For toll-free senders, confirm your verification has been approved by the carrier
• Do not send messages until registration issues are resolved — continued sending risks number suspension

30500 — Internal Messaging Error

What it means An unexpected internal error occurred within the messaging platform — this is a platform-side failure, not a content or number issue.

Common causes

• Transient infrastructure error on Twilio's or a carrier's backend
• A processing failure for a specific message that doesn't indicate a systemic problem

What to do next

• Retry once after a short delay
• If the error repeats consistently for a specific message, contact Twilio support with the message SID for investigation
• Check the Twilio Status Page for any active platform incidents

60005 — Invalid or Unsupported Destination

What it means The destination number is invalid, unsupported, or not routable on any available carrier path.

Common causes

• Number format is valid but the number itself doesn't exist or has never been assigned
• Number belongs to a carrier or region that isn't supported for SMS routing
• International number with a country code not enabled on your account

What to do next

• Validate numbers at intake using Twilio Lookup before they enter any send queue
• Check your geographic permissions if the number is international
• Remove persistently unroutable numbers from active campaigns

Final Takeaways

• "Sent" does not always mean delivered
• Many failures are caused by carrier rules, not your system
• Invalid numbers and carrier filtering are the most common issues
• Logging error codes is essential for troubleshooting and optimization

If you frequently see the same errors, it's a signal to adjust message timing, content, or routing — not necessarily to retry harder.