运营商三要素实名认证：完整错误码对照表（code 0/1/2/11/12/13/21/22）

# 运营商三要素实名认证：完整错误码对照表（code 0/1/2/11/12/13/21/22） > **接口**：运营商三要素 - 运营商手机号实名认证 · **apiCode**：1389 · **接入点**：1389-1 > **请求方式**：POST · **返回格式**：JSON · **计费**：按次（ret_code=0 时扣费，具体档位以官方说明为准） > **适用人群**：已接入用户、中高级开发者 > **阅读时间**：6 分钟 > **最后实测核对**：2026-09-07 --- ## 核心要点 - 业务错误码共 **8 个值**（0/1/2/11/12/13/21/22），覆盖认证成功、失败、参数校验、渠道异常四类场景。 - 系统层 `showapi_res_code=0` 与业务层 `ret_code=0` 是两个不同维度的状态码，不要混淆。 - `code=21`（渠道升级暂停）和 `code=22`（渠道维护暂停）属于平台侧异常，用户无法自行修复，需联系 ShowAPI 客服。 --- ## 完整错误码枚举 | code | 含义 | 常见原因 | 处理建议 | |------|------|---------|---------| | 0 | 认证成功 | — | 正常流程，继续业务 | | 1 | 认证失败 | 姓名/身份证/手机号与运营商记录不匹配 | 引导用户重新输入，允许重试 | | 2 | 无该手机号记录 | 该手机号未实名或未接入运营商数据库 | 告知用户该号码可能未实名，引导绑定真实号码 | | 11 | 手机号、身份证或者姓名为空 | 请求参数缺失，或传入了空字符串 | 检查前端表单校验，确保三个必填字段均有值 | | 12 | 身份证校验错误 | 身份证号格式不正确（位数不对、校验位错误） | 引导用户检查身份证号格式 | | 13 | 手机号校验错误 | 手机号格式不正确（非 11 位、含非法字符） | 引导用户检查手机号格式 | | 21 | 渠道升级暂停服务 | ShowAPI 渠道侧临时升级 | 稍后重试，或联系客服确认恢复时间 | | 22 | 渠道维护暂停服务 | ShowAPI 渠道侧计划维护 | 稍后重试，或联系客服确认维护窗口 | > **铁律**：以上 8 个值为文档给出的完整枚举，不可自行补充或截断。 --- ## 系统层 vs 业务层状态码 调用该接口时，返回 JSON 有两层状态码，含义不同： | 层级 | 字段 | 0 的含义 | 非 0 的处理 | |------|------|---------|------------| | 系统层 | `showapi_res_code` | 调用成功，请求已到达业务层 | 检查 `showapi_res_error`，通常是 appKey 无效或网络问题 | | 业务层 | `ret_code` | 业务调用成功（认证成功或失败均有 ret_code=0） | 检查 `code` 字段判断具体业务结果 | **关键区别**：`ret_code=0` 不代表"认证成功"，只代表"本次调用本身成功（会扣费）"。真正判断认证是否通过要看 `code` 字段。 --- ## 归属地字段说明 当 `needBelongArea=true`（默认值）且 `code=0` 时，返回 `belongArea` 对象： | 字段 | 类型 | 说明 | |------|------|------| | `prov` | String | 省名，如"山西"、"四川" | | `city` | String | 市名，如"临汾市"、"成都市" | | `name` | String | 运营商名称，如"移动神州行卡"、"电信星空卡" | | `num` | Number | 号段，如 1362068 | | `provCode` | Number | 省别编码，本省身份证的前几位编码，如 140000（山西）、110000（北京） | | `type` | Number | 运营商类型：**1=移动 2=电信 3=联通 4=广电** | | `order` | String | 渠道订单号，用于追溯 | > **注意**：`belongArea` 是**单对象**，不是数组。不要按数组逻辑遍历。 --- ## 真实返回示例（2026-09-07 实测） 以下是一段认证成功时的完整返回（测试号段，仅供结构参考）： ```json { "showapi_res_error": "", "showapi_res_code": 0, "showapi_res_id": "60740ce48d57ba8f1c10fb44", "showapi_res_body": { "ret_code": 0, "order": "6ddaf1ec67a343dc814c833ff0ae855f", "code": 0, "belongArea": { "num": 1362068, "prov": "山西", "name": "移动神州行卡", "provCode": "140000", "type": 1, "city": "临汾市" }, "msg": "认证成功" } } ``` --- ## 排查路径速查 ``` showapi_res_code != 0 └─► appKey 无效 / 网络问题 → 检查控制台 AppKey 是否有效 showapi_res_code == 0 但 ret_code != 0 └─► 业务调用异常 → 联系 ShowAPI 客服（极少出现） ret_code == 0： ├─► code == 0 → 认证成功，检查 belongArea 使用归属地 ├─► code == 1 → 三要素不匹配 → 引导用户重新输入 ├─► code == 2 → 手机号未实名 → 引导用户绑定真实号码 ├─► code == 11 → 参数为空 → 检查前端表单校验 ├─► code == 12 → 身份证格式错误 → 引导用户修正身份证号 ├─► code == 13 → 手机号格式错误 → 引导用户修正手机号 ├─► code == 21 → 渠道升级中 → 稍后重试或联系客服 └─► code == 22 → 渠道维护中 → 稍后重试或联系客服 ``` --- ## FAQ **Q1：code=0 但 msg="认证失败"是怎么回事？** 不会同时出现。code=0 时 msg 为"认证成功"；code=1 时 msg 为"认证失败"。如果看到矛盾值，说明解析逻辑有 bug，检查代码中对 `code` 和 `msg` 的读取路径。 **Q2：code=1 和 code=2 的区别是什么？** code=1 是"三要素不匹配"，即数据存在但不一致；code=2 是"无该手机号记录"，即该手机号在运营商侧没有实名登记记录。前者引导用户修正输入，后者引导用户绑定真实号码。 **Q3：belongArea 里 type=4 代表什么？** type=4 表示中国广电（中国广播电视网络有限公司），2022 年起广电获得 5G 商用牌照，部分手机号归属广电。 **Q4：code=21/22 时还会扣费吗？** 文档未明确说明。按"ret_code=0 扣费"的字面理解，若系统层返回 ret_code=0 但业务层 code=21/22，理论上仍会扣费。建议在渠道维护期间暂停调用或做好预算控制。 **Q5：身份证号为空时返回 code=11 还是 code=12？** code=11。code=12 仅在身份证号**非空但格式错误**时返回。 --- ## 下一步阅读 - [注册实名校验集成方案](https://www.showapi.com/guides/idcard-phone-auth-scenario-integration-1389) —— 业务层如何处理这些错误码 - [按次计费下的缓存策略](https://www.showapi.com/guides/idcard-phone-auth-cache-cost-1389) —— 相同参数重复查询如何省钱 - [三要素 vs 二要素 vs 四要素方案对比](https://www.showapi.com/guides/idcard-phone-auth-comparison-1389) —— 选型决策参考 --- **- 本系列共 6 篇**：查看[运营商三要素实名认证指南总目录](https://www.showapi.com/guides/idcard-phone-auth-guides-1389)