调用互亿无线预警通知接口后，服务端会返回JSON结果，其中code字段是判断成功与否的关键。返回JSON里除了code，通常还带msg描述与流水号，msg往往是定位问题的线索。联调时看到code不是2，很多同学不知道从何下手。本文整理常见返…
调用互亿无线预警通知接口后，服务端会返回JSON结果，其中code字段是判断成功与否的关键。返回JSON里除了code，通常还带msg描述与流水号，msg往往是定位问题的线索。联调时看到code不是2，很多同学不知道从何下手。本文整理常见返回码含义与排查思路，帮助开发者快速定位发送问题。
成功返回：code=2
当返回code=2时，表示预警提交成功，系统同时返回流水号（短信为smsid），用于后续追踪发送状态。注意提交成功不等于手机一定收到，送达状态需通过回调或控制台查询。语音电话是否被接听、通话时长多少，也要以回调数据为准。
常见错误返回码与排查
- 认证类错误：account或password错误，检查APIID/APIKEY是否填反、是否多空格；
- 手机号格式错误：mobile含空格、加号或位数不对，规范化后重试；
- 内容相关错误：自定义短信未报备模板、content为空或含敏感词；
- 余额不足：账户测试额度或套餐用完，需充值或领取免费额度；
- 频率限制：短时间并发过高，需加限流与重试间隔；
- 模板错误：使用templateid时变量数量或分隔符不符，核对模板变量数；
- 网络超时：请求未到达服务端，检查公网出口与DNS，设置超时与重试；
- 终端拦截：个别号码收不到，多为手机管家拦截，可改用闪信或语音通道；
返回结果示例
成功提交后返回大致结构如下：
{
"code": 2,
"msg": "提交成功",
"smsid": "202609281234567890"
}排查时先打印完整返回体，根据code与msg对照上表定位。遇到不确定的错误码，可连同请求参数联系技术支持核对。
排查建议
- 先用控制台在线调试工具或curl手动发一条，排除代码问题；
- 把APIID、手机号、content分别替换为测试值，二分定位；
- 保留完整请求与响应日志，方便技术支持协助；
- 按成功计费，失败不计费，排查阶段不会产生额外成本；
- 连续失败不要盲目重发，先看返回msg定位根因，避免触发限流。
常见返回码对照表
返回JSON中的code字段是定位问题的入口。下表整理了联调阶段高频遇到的返回码类别与对应排查方向：
| 类别 | 典型表现 | 排查方向 |
|---|---|---|
| 成功 | code=2，带smsid | 提交受理，送达状态看回调 |
| 认证失败 | 提示账号或密码错误 | 检查APIID/APIKEY是否填反、是否多空格 |
| 手机号错误 | 提示号码格式不正确 | 去掉空格、加号，确认11位国内号码 |
| 内容审核 | 提示模板未报备或内容不合规 | 先在控制台报备签名与模板 |
| 余额不足 | 提示账户余额或额度不足 | 充值或领取免费测试额度 |
| 频率限制 | 提示发送过于频繁 | 加限流与重试间隔，避免告警风暴 |
| 模板错误 | 提示变量数量不符 | 核对templateid与content变量个数 |
用返回码写自动重试逻辑
并非所有错误都该重试。网络超时、服务端瞬时错误适合间隔2秒重试一到两次；认证错误、手机号格式错误属于参数问题，重试无意义，应直接记录日志并告警开发；余额不足应触发充值提醒而不是反复重发。下面是一段简化的判断逻辑：
def handle_result(resp):
code = resp.get("code")
if code == 2:
return "success"
if code in (NETWORK_RETRYABLE,):
time.sleep(2)
return "retry"
return "fail: " + resp.get("msg", "")日志留痕建议
- 把请求参数（脱敏后的手机号）与完整返回体都写进日志；
- 记录smsid，便于和回调状态对账；
- 连续失败计数，超过阈值触发额外告警；
- 按成功计费、失败不计费，排查阶段反复试发不会产生额外成本。
返回msg里的中文描述是排查的直接线索，建议把它完整落库，而不是只记code数字。
掌握返回码就能自助解决大部分联调问题。前往注册免费试用开始调试。