SMS 投递错误

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

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

读取错误

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

通过 API，读取 GET /v1/sms/messages/{message_id}。其 last_error 包含：

失败 webhook 事件和消息时间线事件在 error 中包含相同的字段。

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

标准化失败原因

以下是消息 API定义的失败原因。供应商回执可能包含比标准化原因更具体的数字代码。例如，带有 code: unknown 的消息仍可携带一个已识别的 carrier_error_code。

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

供应商错误代码

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

在 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 日志：查看消息及其投递历史。
• SMS 事件：消费投递和失败 webhook。
• SMS 指标：查看汇总的失败结果。
• SMS API 错误：解读 API 请求返回的错误。