SMS delivery errors
An unsuccessful SMS has a delivery status and an error explaining the outcome. Use this reference to interpret the failure reason and numeric provider code reported with a message.
Request errors such as an invalid send payload use the API error catalog. The codes on this page describe messages that were accepted and later failed or were rejected.
Reading the error
Open a message in the SMS log and select Details. Error shows the description and normalized failure reason. Carrier error code shows the numeric provider code when one was supplied.
Over the API, read GET /v1/sms/messages/{message_id}. Its last_error contains:
| Field | Meaning |
|---|---|
code | Bird's normalized failure reason, such as unreachable or unknown |
description | The reported explanation in words |
carrier_error_code | The provider's raw code, when supplied |
occurred_at | When the failure occurred |
Failure webhook events and message timeline events carry the same fields in error.
The field name carrier_error_code also covers codes issued by Bird's sending provider, including fraud protection blocks. A missing code means the provider supplied none or the message was refused before submission.
Normalized failure reasons
These are the failure reasons defined by the message API. Provider receipts can contain a more specific numeric code than the normalized reason reflects. For example, a message with code: unknown can still carry a recognized carrier_error_code.
| Reason | Meaning |
|---|---|
invalid_destination | The number is unassigned or invalid |
unreachable | The handset is off or outside coverage |
blocked_by_carrier | The receiving carrier filtered the message |
blocked_by_fraud_protection | Bird fraud protection blocked suspected SMS pumping |
blocked_by_recipient | The recipient's device blocked the sender |
landline_unreachable | The landline does not accept SMS |
content_rejected | The carrier rejected the content |
sender_unregistered | The sender lacks required registration |
recipient_opted_out | The recipient is on a suppression list |
provider_unavailable | The provider or network was unavailable |
insufficient_balance | The workspace wallet could not fund the send |
unknown | The failure could not be classified |
This is an open set: accept unfamiliar values and retain the description and raw code for investigation. A temporary cause still ends this message attempt; it does not guarantee automatic resubmission.
Provider error codes
Look up the numeric string returned in carrier_error_code. These codes belong to Bird's SMS sending provider; a different provider may assign other meanings to the same numbers.
| Code | Meaning |
|---|---|
0 | No error |
1 | Unknown subscriber |
2 | Unknown base station |
3 | Unknown mobile switch |
5 | Unidentified subscriber |
7 | Handset cannot connect |
8 | Roaming forbidden |
9 | Subscriber authentication failed |
10 | SMS bearer unprovisioned |
11 | SMS service unprovisioned |
12 | Handset blacklisted |
13 | SMS service barred |
21 | SMS unsupported |
26 | Network handover failed |
27 | Subscriber unavailable |
28 | Outside coverage |
29 | Handset switched off |
30 | Mobile switch failure |
31 | Subscriber busy |
32 | SMS delivery failure |
33 | Pending-message storage full |
34 | Network system failure |
35 | Required data missing |
36 | Unexpected message-field value |
39 | Roaming routing-number unavailable |
40 | Network memory exhausted |
71 | Unsupported alphabet |
72 | USSD busy |
100 | Insufficient sending balance |
101 | Insufficient subscriber balance |
103 | Subscriber opted out |
104 | Sender unregistered |
105 | Content unregistered |
106 | Campaign volume exceeded |
107 | Campaign throughput exceeded |
110 | Operator filtered message |
130 | SurgeGuard detected traffic pumping |
131 | SurgeGuard blocked suspected pumping destination |
Code 0 is omitted from carrier_error_code on Bird message and event reads. An unfamiliar code should remain available in your records when you contact support.
Fraud protection blocks
SurgeGuard is Bird's SMS fraud protection.
Messages blocked by fraud protection have the failure reason blocked_by_fraud_protection and the description "Blocked by fraud protection: suspected SMS pumping." The delivery status remains failed, rejected, or expired, according to the provider's report. The same reason and description appear in message details, timeline events, and failure webhooks. The raw provider code remains available in carrier_error_code when supplied.
In the SMS log, filter Failure reason by Blocked by fraud protection to find these messages.
Older records may still show unknown and generic_delivery_failure. These labels alone do not identify a fraud protection block. Look up their carrier_error_code in Provider error codes to identify the cause. If the code is missing or unfamiliar, contact support with the workspace ID, message ID, timestamp, and provider code, if supplied.
When investigating a blocked OTP, correlate the SMS with the account or verification request that triggered it. Avoid automatically resending or switching routes to bypass the block. If you suspect a legitimate request was blocked, contact support with the workspace ID, message ID, timestamp, and provider code.
Next steps
- SMS log: inspect a message and its delivery history.
- SMS events: consume delivery and failure webhooks.
- SMS metrics: review aggregate failure outcomes.
- SMS API errors: interpret errors returned by an API request.
Related resources
Continue with the documentation, guides and examples for this topic.