排查短信问题要先区分“接口没提交成功”“提交成功但发送失败”“发送成功但用户未收到”。这份指南把常见现象拆成可执行步骤，帮助运营、客服和开发快速定位下一步。
先判断问题类型
| 现象 | 优先看哪里 | 常见原因 |
|---|
| 接口返回错误 | API 返回码、请求参数、接口账号和密钥。 | 参数缺失、签名错误、编码问题、余额不足。 |
| 提交成功但失败 | 发送记录、状态报告、错误码说明。 | 模板、签名、号码、内容审核或通道状态。 |
| 显示成功但用户未收到 | 接收手机号、终端拦截、发送时间、运营商状态。 | 手机拦截、号码异常、延迟、用户终端问题。 |
| 控制台测试失败 | 账号状态、余额、签名模板、测试手机号。 | 账号未准备好、内容不合规、余额不足。 |
| 营销短信异常 | 退订规则、内容审核、号码来源、发送时间。 | 合规要求或内容审核问题。 |
接口返回错误排查
- 先记录接口返回码、请求时间、业务订单号和手机号脱敏信息。
- 对照 API 文档确认请求地址、请求方式、参数名称、编码方式和必填项。
- 检查接口账号和密钥是否来自当前账号，避免测试账号与正式账号混用。
- 如果是余额、签名或模板相关错误，回到计费、签名模板和控制台记录继续确认。
- 不要只截一张失败截图，排查时应保留请求摘要、返回码和发送记录。
验证码收不到排查
| 检查项 | 怎么确认 | 处理动作 |
|---|
| 手机号 | 确认国家区号、手机号格式、是否停机或欠费。 | 更换测试手机号或修正格式。 |
| 发送记录 | 查看是否有提交记录、状态和失败原因。 | 没有记录则回查接口调用。 |
| 模板内容 | 确认签名、验证码变量、有效期和文案是否符合规则。 | 调整模板后重新测试。 |
| 频控策略 | 检查同手机号、同 IP、同账号是否短时间多次触发。 | 增加冷却时间或人机校验。 |
| 终端拦截 | 查看手机短信拦截箱、系统通知权限和安全软件。 | 使用不同号码交叉测试。 |
发送记录与状态报告
| 资料 | 作用 | 谁使用 |
|---|
| 发送记录 | 查看每条短信的提交时间、手机号、内容摘要和状态。 | 运营、客服、开发。 |
| 状态报告 | 把最终发送结果回传给业务系统。 | 开发和后端系统。 |
| 错误码 | 解释接口返回或发送失败的原因。 | 开发、技术支持。 |
| 业务订单号 | 把短信请求和业务动作关联起来。 | 开发、客服、运营。 |
需要支持时准备什么
| 信息 | 为什么需要 |
|---|
| 发送时间范围 | 用于定位对应批次和通道状态。 |
| 手机号脱敏信息 | 保护隐私，同时能辅助定位记录。 |
| 接口返回码或失败状态 | 判断是参数、账号、模板还是发送链路问题。 |
| 短信签名和模板名称 | 确认内容审核和报备情况。 |
| 业务场景说明 | 区分验证码、通知、营销或国际短信。 |
