一、先判断失败发生在哪个阶段
| 阶段 | 典型现象 | 优先检查 |
|---|---|---|
| 请求前 | 客户端校验失败或未调用接口 | 业务逻辑、号码格式、必填字段 |
| API阶段 | 401、403、400、429或5xx | 密钥、权限、参数、限流和平台状态 |
| 平台阶段 | 已接收但未进入有效路由 | 余额、国家支持、模板、Sender ID |
| 运营商阶段 | 异步回执显示拒绝或不可达 | 号码、内容、当地规则、运营商网络 |
| 设备阶段 | 设备离线、无信号或存储问题 | 最终回执、重试时机和消息有效期 |
二、号码格式和号码质量问题
国际短信建议使用E.164格式，即“+国家码+本地号码”。常见问题包括遗漏国家码、重复添加本地前缀、保留空格或括号、号码长度错误，以及把固定电话或不支持短信的号码当作手机号码。
企业应在导入和发送前完成标准化、国家识别、长度校验、重复号码清理和退订名单排除。号码曾经有效也不代表永久有效，停机、携号转网和重新分配都可能影响结果。
排查建议：使用相同模板向同一国家的多个真实号码测试。如果只有个别号码失败，优先检查号码和设备；如果大量号码同时失败，优先检查通道和配置。
三、模板和内容导致的失败
模板未审核、变量缺失、品牌名称不一致、内容包含受限词语或可疑链接，都可能导致消息被拒绝。营销内容还可能受到发送时间、用户同意、退订说明和频率限制影响。
动态变量必须限制长度和字符范围。用户输入不能未经处理直接写入模板。链接应使用企业自有HTTPS域名，避免频繁变更域名或使用来源不明的短链接。
- 核对实际短信是否与已批准模板一致。
- 检查变量是否为空、超长或包含异常字符。
- 确认品牌名称、Sender ID和链接域名一致。
- 检查短信是否因Unicode或长度被拆成多段。
- 区分验证码、事务通知和营销短信通道。
四、Sender ID和国家规则
目标国家可能不支持当前Sender ID类型，或者要求提前注册品牌身份。某些国家允许字母品牌名但不支持回复，另一些市场要求当地号码、短码或指定模板。
不能假设同一Sender ID能够直接用于全部国家。应按国家维护发送身份、模板、用途和注册状态，并在真实设备上检查最终显示。如果失败集中在特定国家，Sender ID和当地规则是重点排查方向。
五、通道路由和运营商问题
平台可能因为路由暂时不可用、吞吐量限制、运营商维护或网络异常而发送失败。此类问题通常会同时影响一批相似国家、运营商或模板。
企业应查看失败是否集中在同一时间、国家、运营商和路由。如果是临时故障，可以使用备用路由或有限重试；如果是内容或身份被拒绝，切换路由并不能真正解决问题。
| 表现 | 可能方向 |
|---|---|
| 多个国家同时失败 | 平台账户、API、余额或系统级故障 |
| 单一国家集中失败 | 当地规则、Sender ID或国家路由 |
| 单一运营商集中失败 | 运营商过滤、网络或路由质量 |
| 单一模板集中失败 | 内容、变量、链接或模板审批 |
六、用户设备和网络状态
用户关机、长期无信号、漫游限制、设备存储异常或号码停机，都可能导致短信暂时不可达或最终失败。设备类问题通常无法通过立即重复发送解决。
应设置消息有效期和最大重试次数。验证码如果已经过期，继续发送旧验证码会造成安全和体验问题；预约或物流通知超过业务时间后，也应停止重试。
七、推荐的排查步骤
- 取得业务ID、message ID、手机号国家和发送时间。
- 确认API请求是否成功以及是否返回平台错误。
- 查看最终状态回执、原始错误码和状态时间线。
- 检查号码格式、国家支持和号码类型。
- 核对模板、变量、Sender ID、链接和短信类型。
- 比较同国家、运营商和模板的其他发送结果。
- 判断错误是永久、临时还是未知，再决定是否重试。
- 修复后先小规模测试，不要直接恢复大批量发送。
八、如何降低未来失败率？
- 发送前标准化号码并维护无效号码抑制名单。
- 按国家管理Sender ID、模板和当地规则。
- 分离OTP、通知和营销流量及队列。
- 建立错误码映射、状态回执和失败趋势监控。
- 对异常失败率、回调中断和队列积压设置告警。
- 定期进行多国家、多运营商真实设备测试。