SMS Delivery Fails with Some Phone Numbers when Twilio is the SMS Provider "21211 Invalid 'to' phone number"

Knowledge Articles
1

Problem statement

We have users reporting that SMS messages are no longer delivered. The error message received is “21211 Invalid ‘to’ phone number.”

Symptoms

  • Users report non-delivery of SMS messages and are presented with the error “21211 Invalid ‘to’ phone number.” This problem may occur randomly or be present for an extended period of time.
  • The problem may impact only a single number or a small number of phone numbers. The majority of SMS message deliveries to non-affected numbers result in successful ‘SMS Sent’ events.

Troubleshooting

  1. Look in the tenant logs for successful ‘SMS Sent’ events: use the search string gd_send_sms. The complete list of all recent such events should be displayed.
  2. Look in the tenant logs for ‘Error Sending MFA SMS’ messages: use the search string gd_send_sms_failure. The complete list of all recent such events should be displayed.

A few points to note about these SMS delivery failures. Click on the body of an individual log event and open it up to inspect the content:

  • These failures are associated with the formal description “Guardian - There was an error sending the SMS.”
  • Scroll down towards the bottom and you will see two blocks like this:
  "failure_details": {
      "errorCode": "invalid_phone_number",
      "message": "Invalid phone number"
    },
    "provider_error": {
      "errorCode": 21211,
      "message": "The 'To' number +166321456 is not a valid phone number."
    }

Of course, there may be other reasons why SMS delivery has failed. However, for the purposes of this article, the focus will be on the error “The ‘To’ number is not a valid phone number.”

One limitation to note is the type of Auth0 subscription plan for which your tenant is enrolled. For example, a basic plan would only provide 2 days’ worth of tenant logs. By contrast, an Enterprise plan would provide 30 days of logs.

If it is not possible to find the relevant error in the logs, ask the user to attempt another SMS authentication using that same number. Request them to record the time/date in UTC and the IP address. If that succeeds, it would suggest that the problem is intermittent. If it fails, the time/date and IP address will make the event easier to pinpoint in the tenant logs.

Cause

The 21211 error is specific to the Twilio SMS service.

In this case, the SMS message service uses the built-in SMS provider. Auth0 has a basic account with Twilio for this purpose.

Note that this problem may also be experienced by customers who have a paid subscription to Twilio.

Solution

First, consider the case of Using the built-in provider: This facility is intended only to enable testing the most basic SMS functionality. Auth0 does not provide any kind of guarantees as to the reliability or quality of service. The built-in provider should not be used in a Production environment. Furthermore, it has a limit of 100 messages for the lifetime of the tenant. This is explained in our public documentation: Configure SMS and Voice Notifications for MFA - Use the Dashboard

"Auth0: You can’t use this provider to send voice messages. Sends SMS messages using Auth0’s internally-configured SMS delivery provider. It can be used for evaluation and testing purposes only, and there is a maximum of 100 messages per tenant during the entire tenant lifetime. New codes are not received after reaching the 100 message limit."

The first recommendation would be to upgrade to using a dedicated SMS provider. This can be either Twilio or one of the other supported providers: Configure SMS and Voice Notifications for MFA - Integrated SMS messaging providers

A paid subscription to an SMS provider should normally come with access to technical support, service logs, and the service knowledge base.

Second, in terms of how to respond to the specific ‘21211’ error, if the precise answer cannot be easily found in the Twilio logs or knowledgebase, create a ticket with Twilio’s help desk and inquire as to why SMS message deliveries appear to be failing for that specific number. This is not something that Auth0 can help you with.

More generally, consider the case where Twilio is configured as the SMS provider and ‘Error Sending MFA SMS’ messages can be found in the tenant logs. If these logs contain an error message with a numeric code like ‘21211’, the first step should be to check the Twilio API reference , in order to understand the nature of the error.

Customers with a paid subscription or a trial subscription with Auth0, open a support ticket in Support Center, with details of the error that has been seen. Not all ‘invalid phone number’ types or errors may originate with Twilio (or other SMS providers).

Free tenant customers should post a question to our [Community