Skip to main content

Troubleshooting Messaging Issues

Messaging is an ever-changing ecosystem, and resolving issues can be tricky. This guide will go over all the common errors that we see and how you can go about quickly resolving them.

Still need help?

If these steps to resolve your issue do not help, SignalWire Support can investigate what went wrong with our carrier peers.

Please open a support request from the top navbar of your Dashboard and include a minimum of 3 or more message SIDs that were flagged with the relevant error. Per our carrier peers' requirements, these SIDs MUST be from the last 24 hours.

List of errors

21717 - From must belong to an active campaign

Error 21717 means that you are trying to send a message from a 10DLC number that is not currently associated with an active messaging campaign. Beginning on March 1st 2022, all 10DLC SMS traffic must be registered with a messaging campaign. You can create a campaign from the Messaging Campaigns section of your SignalWire Space. To learn more about The Campaign Registry, you can reference our documentation here.

30001 - Exceeded Validity Period

If you receive error code 30001, it means that the message sent to SignalWire was correctly placed in the queue for sending. However, upon reaching its turn to be sent, the validity period specified in the ValidityPeriod parameter was expired and the message was no longer valid, so the sending failed. Note that if the ValidityPeriod parameter is not set upon creating a message, it will default to a value of 14400 seconds, or 4 hours.

The most common reason for this error is sending to SignalWire messages at a rate that is faster than the number of messages per second the "From" phone number can deliver at. Another possible reason is having set the ValidityPeriod parameter to a very low value, such as 5 seconds.

Steps to Resolve

  • Can you limit the rate at which messages are being sent to SignalWire, so that it matches or is lower than the maximum messages per second that the sender phone number can deliver?
  • Are you setting the ValidityPeriod parameter upon creation of a message? If not, consider setting this parameter for a longer than default value.

30002 - Insufficient Account Balance to send message

If you receive error code 30002, this means that the message was not sent due to insufficient funds in your SignalWire account. SignalWire will continue to return this error until the account balance is sufficient to cover the cost of the message.

Steps to Resolve

  • Add funds to your SignalWire account to cover the cost of the message.
  • You can set up Auto Top-up to automatically add funds to your account when your balance falls below a certain threshold. You can learn more on how to set up Auto Top-up here.

30003 - Unreachable Destination Handset

If you receive error code 30003, this means that the delivery of your message failed as the destination handset you are trying to reach is switched off or not available.

There are a number of possible reasons for this error:

  • Destination handset intended to be reached isn't on or isn't available.
  • Device/destination handset's signal isn't sufficient enough
  • Destination handset/device isn't capable of receiving SMS, such as a landline number
  • Mobile carrier has an issue

Steps to Resolve

  • Is the destination headset/device on?
  • Is there a sufficient signal on the destination headset/device? Try powering off, wait 30 seconds, then power back on
  • Is the destination device connected to the main carrier network? Message delivery cannot be guaranteed on devices that are roaming off-network.
  • Can SMS from regular cell phones be received on the device?
  • Try sending a message from another SignalWire number or with a shorter one-segment body.
  • Can other devices on the same mobile carrier receive messages?
  • If you are on long code, are you following all carrier regulations? This can occasionally be caused due to carrier filtering.
Short Code

When this error is received on short codes, the cause can be due to the recipient's wireless plan not supporting shortcode (or "Premium") messages.

30004 - Carrier Responded as Undeliverable – Opt Out

This error indicates that the message was not delivered because the recipient previously opted out of receiving messages, usually with a STOP reply.

Steps to Resolve

If the recipient opted out by mistake, advise them to send an unstop message to the sending number. If the recipient did opt out, remove the number from your subscriber list to avoid this error going forward.

30005 - Unknown Destination Handset

If you tried to send out messaging and received error code 30005, this means that when the carrier attempted to deliver your message to the handset, it failed due to an inactive or unknown destination number. It could be that the phone number is no longer in service or is not recognized as owned by any carrier.

Steps to Resolve

The first step is to check if the "To" number is valid and has active mobile service at this time. It may be helpful to check when the user opted into your services to see if there is any chance the phone may now be inactive. If you are able to confirm this is a correct and valid number, try the following steps:

  • Is the device able to receive SMS from regular cell phones as opposed to VOIP phones?
  • Is the device able to receive text messages from toll-free numbers (if you are sending on toll-free)?
  • Is the device able to receive messages from other SignalWire numbers?
  • Is the device able to receive a one-segment message?
  • Is the device connected to the home carrier's network and does it have sufficient signal?

30006 - Landline or Unreachable Carrier

If you received error code 30006, this means that the destination handset you were trying to reach was determined by the carriers to be either a landline or a number owned by an unreachable carrier.

Steps to Resolve

You can use the Phone Number Lookup API in order to verify if the destination number is a landline or what the associated carrier may be. In most cases, it is best to remove these numbers from your sending lists as they are categorized as unreachable.

30007 - Message Marked as Spam

Error code 30007 means that you were flagged as spam by not following the rules set forth for messaging. This could be a flag from SignalWire or from the upstream carriers for violating regulations.

Steps to Resolve

  • The first step is to review best practices for messaging and make sure that you are following all of these rules.
  • The second step is to ensure that if you are messaging from local long code numbers, you are registered with The Campaign Registry and following all their rules.
  • If you believe that your messages are following all of the above rules and you are still being flagged, you can reach out to our support team with examples. They can help determine if an error was made or assist in correcting your messaging where needed.

30008 - Unknown Error

Error code 30008 happens when the carriers do not give us any details or reason for failure leaving it only as failed for unknown reasons.

Steps to Resolve

  • Check that the receiving phone is turned on and can receive non-SignalWire SMS
  • Ensure that the phone is not roaming off the network. Message delivery cannot be guaranteed on roaming phones.
  • Try sending to other phones who have the same mobile carrier. If messages to other phones are delivered, the issue is likely device-related. Try rebooting the device or contact the mobile carrier for help.
  • If the recipient number is another SignalWire number, ensure that number has an action configured for its Messaging capabilities. Make sure that each number has a webhook or application set up to handle inbound messaging.
  • Try sending a shorter message to the phone that has simple content and does not include any special characters. This would give our support team an idea as to whether the failure is related to concatenation or character encoding.

30022 - Campaign Registry Throughput Limits Exceeded

Error 30022 means that you have exceeded your limits as dictated by the Campaign Registry, or your message has been flagged as spam. Please refer to the max throughput per minute you were assigned by AT&T or the daily limit for T-Mobile.

Steps to Resolve

Use the Phone Number Lookup API to determine the carrier of the failed message.

If it's T-Mobile:

  • Review your approved daily message segment limit set by T-Mobile.
  • SignalWire does not track this daily limit, so messages are not blocked when your limit is exceeded.
  • Ensure when sending out that you are not surpassing that limit to T-Mobile numbers each day to avoid getting blocked again.
  • If your campaign has not reached its daily limit, please refer to our guide on SMS Best Practices to avoid messages being flagged as spam.

If it's AT&T:

  • Review your approved message segment per second/minute limit set by AT&T.
  • Ensure that in future sends, all numbers in the campaign are not sending more than the total segments per minute. For example, if you are sending a 1 segment message from 4 numbers and you have 240 Segments per Minute approved, each number may send at no more than 60 messages per minute.
  • SignalWire throttles messages to AT&T for you according to your limit, so this error is more likely caused by the message being flagged as spam. Please refer to our guide on SMS Best Practices to avoid repeat spam flags.