Handling SMS Messaging Errors

SMS message delivery can fail for a variety of reasons, such as invalid phone numbers, carrier filtering, network issues, or recipient device problems. Successfully invoking the SMS API—whether to send a single message or a batch of messages—only confirms that the request was accepted by the system. It does not guarantee that the messages will be delivered to the intended recipient(s). Delivery status should always be verified through the message record updates provided by the API.

If the API successfully pushes a message to the sending queue, it creates a corresponding message record and stores it in the message store database. This record serves as a persistent log, allowing developers to track the message’s lifecycle, query its status, and retrieve its content when needed.

• When a message is sent and successfully delivered, its record will be updated with the status "Delivered", as shown in the example below:

{
  "to": [
    {
      "phoneNumber": "+1650513XXXX"
    }
  ],
  "from": {
      "phoneNumber": "+1209509XXXX"
  },
  "messageStatus": "Delivered"
  ...
}

• If a message fails to send, its record will be updated with the corresponding status and error code, as shown in the example below:

{
  "to": [
    {
      "phoneNumber": "+1650513XXXX"
    }
  ],
  "from": {
      "phoneNumber": "+1209509XXXX"
  },
  "messageStatus": "SendingFailed",
  "deliveryErrorCode": "SMS-RC-413",
  ...
}

SMS Error Code Structure

SMS error codes consist of a prefix and a numeric value. The prefix identifies the source reporting the error, while the numeric portion represents the specific error code. For example, in SMS-CAR-411, the prefix is SMS-CAR- and the numeric code is 411. There are 3 sources that can return an error:

Common Errors

Commonly encountered errors fall into categories:

1. Sending to invalid numbers such as landline numbers or other numbers that cannot support SMS messaging.
2. Being rejected as spam.
3. Being rejected by carriers due to daily/monthly throughput limits on your TCR brand and campaign.
4. Not enough credits.
5. Number is blocked due to compliance violation.
6. The recipient opted out.

Error Code List

Error returned by RingCentral Messaging Service

Error returned by RingCentral SMS Upstream (Gateway)

Error returned by a Carrier