短信接口错误码说明

本页用于排查短信接口返回码和发送失败问题。请先确认当前调用的是接口 v1 还是接口 v2：v1 返回文本返回码，v2 返回 JSON 的 code 字段。两个版本的部分状态码含义不同，不能混用。

查看 v2 状态码查看 v1 返回码发送失败排查

先确认接口版本

版本	返回格式	成功判断	文档
v1	文本返回码。	返回文本等于 0。	国内短信 API v1
v2	JSON，包含 code、msg、data。	code 等于 0。	国内短信 API v2

接口 v2 状态码

状态码	说明	处理动作
0	成功。	读取 data，例如短信发送成功时读取 data.taskId。
30	请求参数不全。	检查 username、secret、to、content 等必填参数。
40	账号或密码错误。	核对 username 和 secret 是否正确。
41	余额不足。	检查账户余额、套餐余量或对应产品余额。
42	账号已过期。	登录后台确认账号状态，必要时联系客服。
43	IP 地址限制。	确认调用服务器出口 IP 是否在允许范围内。
44	账号已被禁用。	停止重试，登录后台或联系客服确认账号状态。
51	内容含有敏感词。	检查短信内容、签名、模板变量和营销合规要求。
52	手机号码格式不正确。	检查号码格式、英文逗号分隔和空格。
53	没有可用的短信产品。	确认账号是否开通对应短信产品或 product 是否正确。
54	试用账号无权调用此接口。	确认账号权限或升级为正式账号。
55	错误的账号。	核对账号来源和调用环境。
70	模板格式不正确。	检查模板内容、变量格式和签名。
71	验签失败。	检查密钥、签名算法或请求来源。

接口 v1 返回码

返回码	含义	处理动作
0	提交成功。	继续查看发送记录或状态报告，确认最终送达状态。
30	错误密码。	检查 p 参数是密码 MD5 还是 ApiKey，确认账号环境一致。
40	账号不存在。	检查 u 参数，确认用户名和短信宝后台账号一致。
41	余额不足。	检查账户余额、套餐余量和产品余量。
42	账号已过期。	登录后台确认账号状态。
43	IP 地址限制。	确认调用服务器出口 IP 是否在允许范围内。
50	内容含有敏感词。	检查签名、模板、变量和实际发送内容。
51	手机号码不正确。	检查手机号格式、分隔符、空格和号码来源。
60	尚未充值，接口不可调用。	先完成充值或确认账户产品状态。

状态报告内部代码

状态码	说明
LO:0103	余额不足。
LO:0800	没有合适的通道可用。
LO:0801	网关转发短信提交失败。
LO:0802	网关连接异常。
LO:0803	号码不正确。
LO:0804	敏感字。
LO:0805	黑名单。
LO:0806	敏感字。
LO:0807	通道不支持长短信。
LO:0808	产品代码不正确或国际余额不足。
LO:0809	相同号码发送间隔时间低于限制值。
LO:0810	相同号码一天接收次数超过限制值。
LO:0900	审核否决。

标准排查流程

步骤	检查内容	判断结果
1. 确认版本	判断请求地址和参数名属于 v1 还是 v2。	避免把 v1 返回码和 v2 状态码混用。
2. 记录现场	保存请求时间、业务单号、返回码、脱敏手机号和调用环境。	确保后续能在发送记录中定位同一条请求。
3. 查账号	检查用户名、ApiKey、secret、账号状态和 IP 限制。	定位账号、鉴权和 IP 类问题。
4. 查余额	检查余额、套餐余量、产品参数和通道余量。	定位余额不足或产品不可用问题。
5. 查内容	检查签名、模板、变量、敏感词和 URL Encode。	定位内容敏感或编码异常问题。
6. 查号码	检查手机号格式、分隔符、空格、国家区号。	定位号码格式问题。
7. 查发送结果	提交成功后继续查看发送记录或状态报告。	确认最终是否成功送达或被运营商拦截。

相关文档

国内短信 API v1查看 v1 请求地址、参数和返回结果。国内短信 API v2查看 v2 JSON 接口和状态码。代码示例按版本查看请求写法和返回处理方式。状态报告 / 发送记录 API接口提交成功后继续确认最终发送状态。发送失败排查从账号、余额、内容、号码和发送记录逐步排查。