Question
What are common error codes I might see when attempting to send outbound SMS with the Vonage SMS API?
Applies To
- Vonage SMS API
- Outbound SMS
- Delivery Receipts
- Error Codes
Answer
All Delivery Receipts with a non-zero error code can be considered as indicating failed delivery. i.e., Your SMS did not reach the recipient.
Neither Vonage SMS APIs nor operators will perform further attempts to re-deliver a message unless another API call is performed.
Vonage SMS API Error Codes
The err-code
field in the DLR provides more detailed information and can help troubleshoot a failed delivery. A non-zero code indicates that the message could not be delivered.
err-code |
Meaning | Description |
---|---|---|
0 | Delivered | Message was delivered successfully. |
1 | Unknown | Message was not delivered and no cause could be determined. |
2 | Absent Subscriber - Temporary | Message was not delivered because handset was temporarily unavailable. Retry. |
3 | Absent Subscriber - Permanent | Number is no longer active and should be removed from your database. |
4 | Call Barred by User | Permanent error. Number should be removed from your database and the user must contact their network operator to remove the bar. |
5 | Portability Error | Issue relating to portability of the number. Contact the network operator to resolve it. |
6 | Anti-Spam Rejection | Message blocked by carrier's anti-spam filter. |
7 | Handset Busy | Handset not available at the time message was sent. Retry. |
8 | Network Error | Message failed due to network error. Retry. |
9 | Illegal Number | User has requested not to receive messages from a specific service. |
10 | Illegal Message | Error in message parameter, e.g., wrong encoding flag. |
11 | Unroutable | Vonage cannot find a suitable route to deliver the message. |
12 | Destination Unreachable | Route to number cannot be found. Confirm the recipient's number. |
13 | Subscriber Age Restriction | Target cannot receive message due to their age. |
14 | Number Blocked by Carrier | Recipient should ask their carrier to enable SMS on their plan. |
15 | Prepaid Insufficient Funds | Recipient is on a prepaid plan and does not have enough credit to receive your message. |
16 | Gateway Quota Exceeded | Message delivery failed because the allowed number of requests per period was exceeded. NB: This error is shown for accounts registered in the US and France only. |
17 | Message Blocked by Provider | The messaging provider has chosen to block this message. This may be due to content or restrictions imposed by the provider. |
50 | Entity Filter | Message failed due to entity-id being incorrect or not provided. See more information on country specific regulations. |
51 | Header Filter | Message failed because the header ID (from phone number) was incorrect or missing. See more information on country specific regulations. |
52 | Content Filter | Message failed due to content-id being incorrect or not provided. See more information on country specific regulations. |
53 | Consent Filter | Message failed due to consent not being authorized. See more information on country specific regulations. |
54 | Regulation Error | Unexpected regulation error. |
99 | General Error | Typically refers to an error in the route. |
Additional Information
For more information on issues sending SMS, see Troubleshooting SMS Delivery.
Articles in this section
- SMS Best Practices During COVID-19 for Users Sending Traffic to North America
- Troubleshooting SMS Delivery
- Global Sender ID Portal - FAQs
- Global Sender ID Registration Guide
- Recommended Sender ID option for A2P Alert and Transactional Messages to US Virtual Numbers
- Partner Quota Violation Error
- SMS Delivery Failure Error 95 - Unknown
- DLR Statuses
- Is USSD supported via SMS for the SMS API?
- What countries require STOP management for recipient opt-out?