# 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](/docs/api/errors). 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](/docs/guides/sms/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}`](/docs/api/reference/get-sms-message). 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](/docs/guides/sms/events#failure-events) and [message timeline events](/docs/api/reference/list-sms-message-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](/docs/api/reference/get-sms-message). 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](#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](/docs/guides/sms/sms-log): inspect a message and its delivery history.
- [SMS events](/docs/guides/sms/events): consume delivery and failure webhooks.
- [SMS metrics](/docs/guides/sms/tracking-and-metrics): review aggregate failure outcomes.
- [SMS API errors](/docs/api/errors/E12xxx): interpret errors returned by an API request.

## Related resources

- [Sending your first SMS](/learn/sms/sending-your-first-sms) (video)
- [What does SMS mean?](/explained/sms/what-does-sms-mean) (answer)
- [SMS](/sms-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=sms)