---
title: "SMS 投递错误"
description: "在消息详情、投递回执和 webhook 中查询 SMS 失败原因和数字提供商代码，包括欺诈保护拦截。"
canonical: "https://bird.com/zh-sg/wendang/guides/sms/delivery-errors"
---

# SMS 投递错误

未成功的 SMS 包含一个投递状态和一条解释结果的错误。使用此参考来解读消息附带的失败原因和数字提供商代码。

请求错误（例如无效的发送载荷）使用 [API 错误目录](/docs/api/errors)。本页中的代码描述的是已被接受但随后失败或被拒绝的消息。

## 读取错误

在 [SMS 日志](/docs/guides/sms/sms-log) 中打开一条消息并选择 **Details**。**Error** 显示描述和标准化失败原因。**Carrier error code** 显示提供商返回的数字代码（如有）。

通过 API，读取 [`GET /v1/sms/messages/{message_id}`](/docs/api/reference/get-sms-message)。其 `last_error` 包含：

| 字段                 | 含义                                                   |
| -------------------- | ------------------------------------------------------ |
| `code`               | Bird 的标准化失败原因，例如 `unreachable` 或 `unknown` |
| `description`        | 以文字形式报告的说明                                   |
| `carrier_error_code` | 供应商返回的原始代码（如有提供）                       |
| `occurred_at`        | 失败发生的时间                                         |

[失败 webhook 事件](/docs/guides/sms/events#failure-events)和[消息时间线事件](/docs/api/reference/list-sms-message-events)在 `error` 中包含相同的字段。

字段名 `carrier_error_code` 同样涵盖由 Bird 的发送供应商返回的代码，包括欺诈保护拦截。代码缺失表示供应商未提供，或消息在提交前即被拒绝。

## 标准化失败原因

以下是[消息 API](/docs/api/reference/get-sms-message)定义的失败原因。供应商回执可能包含比标准化原因更具体的数字代码。例如，带有 `code: unknown` 的消息仍可携带一个已识别的 `carrier_error_code`。

| 原因                          | 含义                                 |
| ----------------------------- | ------------------------------------ |
| `invalid_destination`         | 号码未分配或无效                     |
| `unreachable`                 | 终端已关机或不在服务区               |
| `blocked_by_carrier`          | 接收运营商过滤了该消息               |
| `blocked_by_fraud_protection` | Bird 欺诈防护拦截了疑似 SMS 流量欺诈 |
| `blocked_by_recipient`        | 收件人的设备屏蔽了该发送方           |
| `landline_unreachable`        | 该固定电话不接受 SMS                 |
| `content_rejected`            | 运营商拒绝了消息内容                 |
| `sender_unregistered`         | 发送方缺少必要的注册                 |
| `recipient_opted_out`         | 收件人在屏蔽列表中                   |
| `provider_unavailable`        | 提供商或网络不可用                   |
| `insufficient_balance`        | 工作区钱包余额不足，无法完成发送     |
| `unknown`                     | 无法对该失败进行分类                 |

这是一个开放集合：遇到不熟悉的值时，保留描述和原始代码以便排查。临时原因仍会终止本次消息尝试，但不保证系统会自动重新提交。

## 供应商错误代码

在 `carrier_error_code` 中查找返回的数字字符串。这些代码属于 Bird 的 SMS 发送供应商；不同供应商可能为相同数字赋予不同含义。

| 代码  | 含义                            |
| ----- | ------------------------------- |
| `0`   | 无错误                          |
| `1`   | 未知订阅用户                    |
| `2`   | 未知基站                        |
| `3`   | 未知移动交换机                  |
| `5`   | 未识别的订户                    |
| `7`   | 终端无法连接                    |
| `8`   | 禁止漫游                        |
| `9`   | 订户鉴权失败                    |
| `10`  | SMS 承载未开通                  |
| `11`  | SMS 服务未开通                  |
| `12`  | 终端被列入黑名单                |
| `13`  | SMS 服务被禁止                  |
| `21`  | SMS 不受支持                    |
| `26`  | 网络切换失败                    |
| `27`  | 用户不可用                      |
| `28`  | 不在覆盖范围内                  |
| `29`  | 终端已关机                      |
| `30`  | 移动交换机故障                  |
| `31`  | 用户忙                          |
| `32`  | SMS 投递失败                    |
| `33`  | 待发消息存储已满                |
| `34`  | 网络系统故障                    |
| `35`  | 缺少必需数据                    |
| `36`  | 消息字段值异常                  |
| `39`  | 漫游路由号不可用                |
| `40`  | 网络内存耗尽                    |
| `71`  | 不支持的字母表                  |
| `72`  | USSD 忙                         |
| `100` | 发送余额不足                    |
| `101` | 用户余额不足                    |
| `103` | 用户已退订                      |
| `104` | 发送方未注册                    |
| `105` | 内容未注册                      |
| `106` | 活动量超限                      |
| `107` | 活动吞吐量超限                  |
| `110` | 运营商过滤了消息                |
| `130` | SurgeGuard 检测到流量欺诈       |
| `131` | SurgeGuard 屏蔽了疑似欺诈目的地 |

在 Bird 消息和事件读取中，`carrier_error_code` 会省略代码 `0`。遇到不熟悉的代码时，请保留在记录中，以便联系支持团队时提供。

## 欺诈保护屏蔽

SurgeGuard 是 Bird 的 SMS 欺诈保护功能。

被欺诈保护拦截的消息具有失败原因 `blocked_by_fraud_protection` 和描述 "Blocked by fraud protection: suspected SMS pumping." 投递状态根据供应商的报告保持为 `failed`、`rejected` 或 `expired`。相同的原因和描述会出现在消息详情、时间线事件和失败 webhook 中。原始供应商代码在提供时仍可通过 `carrier_error_code` 获取。

在 SMS 日志中，将**Failure reason**筛选为**Blocked by fraud protection**即可找到这些消息。

较早的记录可能仍显示 `unknown` 和 `generic_delivery_failure`。仅凭这些标签无法确认是否为欺诈保护拦截。请在[供应商错误代码](#供应商错误代码)中查找对应的 `carrier_error_code` 以确定原因。如果代码缺失或无法识别，请携带工作区 ID、消息 ID、时间戳以及供应商代码（如有）联系支持团队。

调查被拦截的 OTP 时，将 SMS 与触发它的账户或验证请求关联起来。请勿自动重新发送或切换路由来绕过拦截。如果你怀疑合法请求被误拦截，请携带工作区 ID、消息 ID、时间戳和供应商代码联系支持团队。

## 后续步骤

- [SMS 日志](/docs/guides/sms/sms-log)：查看消息及其投递历史。
- [SMS 事件](/docs/guides/sms/events)：消费投递和失败 webhook。
- [SMS 指标](/docs/guides/sms/tracking-and-metrics)：查看汇总的失败结果。
- [SMS API 错误](/docs/api/errors/E12xxx)：解读 API 请求返回的错误。

## 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)