How do I troubleshoot mobile text message (SMS) failures in Amazon SNS?

Resolution

Activate CloudWatch Logs

To troubleshoot Amazon SNS SMS message failures, use Amazon CloudWatch Logs to view the providerResponse attribute for the cause of the failure.

To activate CloudWatch Logs for your SMS message, see Viewing CloudWatch Logs. For more information, see How do I access Amazon SNS topic delivery logs for SMS messages?

Note: If your SMS account is in the SMS Sandbox and you need to send SMS messages to unverified phone numbers, then additional configuration is required. For more information, see How do I move my Amazon SNS SMS account from sandbox to production to send messages to unverified phone numbers?

Review your delivery status logs and failed SMS delivery logs

Review your delivery status logs for the "status": "FAILURE" error message. If there's a failure error in the delivery status logs, then troubleshoot the issue based on the error message that you receive. For more information, see SMS delivery failure reasons.

"providerResponse": "No Quota left for account" errors

If you see this error message in the failed SMS delivery logs, then you exceeded your monthly SMS spending quota.

Note: You can also check the CloudWatch SMSMonthToDateSpentUSD metric to confirm whether you exceeded your monthly SMS spending quota.

If you exceeded your monthly SMS spending quota, then request a spending quota increase for SMS messages in Amazon SNS.

Important: After you receive an SMS spending quota increase confirmation, you must also adjust the spending quota for your AWS account. If you don't update your SMS settings on the Amazon SNS console, then your SMS spend limit doesn't increase.

"providerResponse": "delivery would exceed maxprice" errors

If you use an AWS SDK to send SMS messages, then check the failed SMS delivery logs for the "providerResponse": "delivery would exceed maxprice" error. If you see this error in the failed SMS delivery logs, then you exceeded the price limit that's configured in your AWS.SNS.SMS.MaxPrice message attribute.

Note: You can also check the CloudWatch PublishSize metric to check whether you exceeded your message size quota. If Amazon SNS determines that sending the message incurs a cost that exceeds the maximum price that you set, then it doesn't send the message.

If you exceeded your maximum message price limit, then either increase your AWS.SNS.SMS.MaxPrice value or reduce the size of your SMS message. For more information, see Publishing SMS messages to a mobile phone using Amazon SNS.

"providerResponse": "Your account requires additional review prior to being able to send SMS messages" errors

If you see this error message in the failed SMS delivery logs, then AWS didn't approve your account to send SMS messages.

Note: To prevent abuse, AWS must approve your spending quota and use case before you send SMS messages.

If AWS didn't approve your account to send SMS messages, then request a quota increase.

Important: Make sure that you choose Service limit increase for your case type, not Account and billing or Technical.

"providerResponse": "Blocked as spam by phone carrier" errors

If you see this error message in the failed SMS delivery logs, then the carrier blocked the message because of a template issue. For example, the message content doesn't match the registered template, the variable value is too long, or case mismatch issues.

For more information, see Understanding template matching issues when sending messages.

"providerResponse": "Unknown error attempting to reach phone" errors

You might receive the "Unknown error attempting to reach phone" error in your CloudWatch Logs for SMS messages because of multiple reasons. To resolve this issue, check your configuration requirements.

For more information, see How do I resolve the "Unknown error attempting to reach phone" error from SMS through Amazon SNS or AWS End User Messaging?

Confirm that your AWS Region supports your origination identities

Make sure that the country or AWS Region that you send messages to support the origination identities that you use.

For example, to send messages to US destination phone numbers, you must have a supported US origination number TFN/10DLC/ShortCode in your Region. Or, to send messages to CA destination phone numbers, you must have a supported CA origination number LongCode/ShortCode in your Region. Certain countries require senders to meet specific requirements to send SMS messages, such as pre-registering a Sender ID.

For more information, see Supported countries and regions for SMS messaging with AWS End User Messaging SMS.

Related information

Working with shared resources in AWS End User Messaging SMS