先看懂返回结构:两层状态
核验类接口(身份证 / 手机号 / 银行卡)的返回 JSON 是两层结构:
{
"data": { "code": "1000", "message": "一致" }, "status": "2001" }
data.code:业务结果——核验本身"是什么结论、出了什么错"
status:服务状态——"这次请求本身处理得顺不顺"
排查时先看 status 是不是 2001(正常服务),再看 data.code。两个字段要一起看:比如 code=1108 伴随 status=2005(参数异常)是参数问题;若伴随 status=2002(第三方异常)则可能是上游波动,稍后重试即可。
计费码 vs 不计费码:先搞清楚哪些花钱
| 是否计费 | code | 含义 |
| 计费 | 1000 | 一致 |
| 计费 | 1001 | 不一致 |
| 计费 | 1003 / 1004 / 1005 | 手机号三要素详版的部分一致结果 |
| 不计费 | 1002 | 库中无此号 |
| 不计费 | 11xx 全部 | 参数/鉴权/账户类错误 |
行业惯例是"查到结果就计费,没查到结果不计费"——1001 不一致说明权威数据源确实返回了"不匹配"这个结论,属于有效核验。所以格式校验、去重这些前置工作都是省钱的:一条格式错误的请求虽然不计费,但也不产生价值,还占用你的系统资源。
业务结果码(1000-1005)
| code | 含义 | 出现场景与处理 |
| 1000 | 一致 / 验证成功 | 正常放行 |
| 1001 | 不一致 | 先确认用户输入无误;业务上拒绝或转人工 |
| 1002 | 库中无此号 | 多为号码输入错误;建议拒绝并让用户核对 |
| 1003 | 第三方服务异常 | 稍后重试;持续出现联系服务商 |
| 1004 | 手机号与证件号一致,姓名不一致(仅手机三要素详版) | 说明证+号是真的、姓名对不上,常见于家人名下号码 |
| 1005 | 手机号与姓名一致,证件号不一致(仅手机三要素详版) | 号码实名信息与提交的证件不符 |
1004 / 1005 是详版三要素特有的细粒度结果——普通三要素只告诉你"不一致",详版告诉你"哪两个一致、哪个对不上",风控决策可以更精细(比如 1004 可要求用户换号或补充验证)。
系统与鉴权码(1101-1110)
| code | 含义 | 高频原因 |
| 1101 | 商家 ID 不合法 | mall_id 填错,或误把后台登录名当 mall_id |
| 1102 | 姓名不合法 | 姓名含特殊字符、空白,或编码不是 UTF-8 |
| 1103 | 号码编码不合法 | 身份证末位 X 未转小写、位数错误 |
| 1104 | 签名不合法 | 见下方专节 |
| 1105 | 第三方/银联/运营商超时 | 上游波动,可重试(幂等设计下) |
| 1106 | 账户余额不足 | 充值 |
| 1107 | tm 参数不合法 | 用了 10 位秒级时间戳;须 13 位毫秒 |
| 1108 | 参数异常 | 参数名拼写错误;参数无误时检查该产品是否已对账户开通 |
| 1109 | 账户被暂停 | 联系服务商 |
| 1110 | 身份中心超时 | 上游波动,稍后重试 |
1104 排查清单(按命中率排序)
拼接顺序与接口文档不符——注意:不同接口的签名串不一样,有的接口签名不包含全部业务参数(比如银行卡三/四要素的签名串不含身份证号),不要把请求参数"全"拼进去,严格照文档
tm 两处不一致:签名用的 tm 和表单里传的 tm 不是同一个值(必须先生成、两处复用)
编码问题:中文姓名 getBytes 没指定 UTF-8,Windows 开发机默认 GBK,签名必错
大小写:MD5 结果要求 32 位小写
appkey 复制时带了首尾空格
差分排查法:不知道错在哪一层时
当"参数看起来全对却一直报错"时,用故意制造错误的方法定位层次:
把 sign 改坏一位再请求:若返回 1104,说明请求已穿过参数层到达签名校验——参数没问题,查签名逻辑
把 sign 恢复正确仍返回 1108:参数与签名层都过了,问题在更上层的开通状态或账户配置——去商户后台确认对应产品的开通情况
连错误 sign 都换不来 1104:请求可能没到业务层(商户号无效 1101、网络/网关层拦截)
这套方法对任何有参数校验、签名校验、权限校验分层的接口都适用,比对着文档逐字段肉眼排查快得多。
短信接口是另一套码:不要混用
短信验证码接口与核验类接口返回体系不通用:扁平 JSON(没有 data/status 包装),码表也不同:
| code | 含义 | 处理 |
| 1000 | 发送成功(计费) | — |
| 1001 | 商户号不存在 | 短信通道的商户体系独立,确认已开通 |
| 1002 | 签名错误 | 检查 mall_id+phone+code+appkey 拼接,注意不含 tm |
| 1003 | 可发送条数为 0 | 账户短信余量充值 |
| 1004 | 短信内容为空 | 检查 code 参数 |
| 1005 | 内容含敏感词 | 修改模板内容 |
| 1006 | 错误的手机号 | 格式校验 |
| 1007 | 号码在黑名单 | 用户此前退订或投诉过 |
| 1008 | 同号发送频率过快 | 加发送间隔限制(默认 60 秒) |
| 1009 | 内容缺少签名 | 短信内容里必须含【签名】,如"【诺正通】您的验证码…" |
两个最易混的点:① 短信的 code 参数指整条短信内容,不是"验证码数字";② 短信签名不含 tm 时间戳,别套用核验类的签名逻辑。
status 服务状态码
| status | 含义 | 处理 |
| 2001 | 正常服务 | — |
| 2002 | 第三方服务器异常 | 稍后重试 |
| 2003 | 服务器维护 | 关注服务商公告 |
| 2004 | 账户余额不足 | 充值 |
| 2005 | 参数异常 | 核对请求 |
给接入方的三条工程建议
全码监控:把 data.code 的分布做成监控指标。1104 突增多半是发版改坏了签名;1105/1110 突增是上游波动,和业务无关——分开告警能省很多无谓的深夜排查
失败也留痕:1001、1002 这类业务失败要记录请求摘要(脱敏),客户投诉"我明明是他本人"时,这是自证清白的依据
重试只给网络错:1105/1110 可以自动重试一次;1000/1001 这类已有业务结论的绝不重试——重试等于多付一次费
---
接口契约与完整码表以开发者文档为准:通用接入规范;各能力端点签名规则见对应产品页。如需试用(含免费调用额度),可提交申请,1 个工作日内审核开通。