跳到主要内容

错误码

功能说明​

如果 API 调用失败，返回结果中的 code 为非 0 值，message 描述具体错误。例如：

{
  "code": 2080010,
  "message": "user not found in search",
  "requestId": "4d5912a82af144f8a982c2da031c1035",
  "data": {}
}
字段说明
code业务错误码。0 表示成功；非 0 表示失败
message错误的具体信息
requestId请求唯一 ID，排查问题时请务必保留

HTTP 状态码​

HTTP 状态码含义处理建议
200请求已到达业务层检查响应 body 中的 code 字段获取真实结果
401未授权检查 Authorization 头与 API Key 有效性
403禁止访问检查应用是否被禁用或凭证是否被吊销
429请求过于频繁降低 QPS——默认限制为 20 次/秒；如需更高限额请联系官方申请提额
5xx服务端错误稍后重试；若持续出现请联系技术支持并提供 requestId

业务错误码​

业务错误码为 7 位十进制数：前 3 位标识模块，后 4 位标识具体错误。涉及三个号段：

  • 1000xxx —— 通用错误（参数校验、内部异常）
  • 2060xxx —— 凭证/鉴权错误（网关层）
  • 2080xxx —— 掌纹业务错误

通用错误（1000xxx）​

错误码message含义 / 处理建议
0ok成功
1000000invalid param参数校验失败（缺少必填字段、格式非法、长度超限）。请对照接口参数表检查请求
1000001internal error服务端内部错误。稍后重试；若持续出现请联系技术支持并提供 requestId
1000011database operation failed数据库操作失败。稍后重试；若可复现请携带 requestId 上报
1000013forbidden操作无权限（应用被禁用或凭证被吊销）。请在控制台检查应用状态

凭证与鉴权（2060xxx）​

在网关层返回，先于任何业务逻辑执行。

错误码message含义 / 处理建议
2060000unauthorized缺少 Authorization 头，或 API Key 无效/过期。请检查请求头格式与凭证
2060002too many requests触发频率限制（默认：20 次/秒）。请降低 QPS，或联系官方申请提额
2060200openapi credential not found凭证不存在（可能已被删除）。请在控制台确认或重新生成
2060202openapi credential revoked凭证已被吊销。请在控制台重新生成
2060203openapi credential invalid凭证格式非法或签名校验失败。请确认 API Key 复制完整
2060204openapi credential type invalid凭证类型错误——Bearer 后的值必须携带 ak_ 前缀
2060207OpenAPI app not configured应用未在平台配置。请联系技术支持

掌纹业务（2080xxx）​

错误码message含义 / 处理建议
2080000no available version无可用算法版本。请联系技术支持确认产品开通情况
2080001unknown image type未知图片类型。请确保 RgbImage.Data 为有效 Base64 编码的 JPEG/PNG，且 ImageType 为 1
2080002image MD5 mismatch图片数据传输损坏或被截断。请客户端重试
2080003liveness check failed活体检测未通过（可能存在照片/重放攻击）。请引导用户重新拍摄真实手掌
2080004quality check failed图像质量检测未通过（模糊、手掌不完整、光线差）。请引导用户重新拍摄
2080007already bound该 UserId + PalmDirection 已绑定掌纹。可在 RegisterRgbPalm 中设置 IsForce=true 覆盖
2080009data not found数据不存在。指定的 UserId/PalmDirection 没有已注册掌纹
2080010user not found in searchSearchRgbPalm 在掌纹库中未命中任何用户。属正常业务结果，不是系统错误
2080011table capacity full掌纹库分区容量已满。请联系技术支持扩容
2080014palm capacity full应用掌纹库容量已达上限。请删除无用掌纹，或联系官方申请扩容
2080016user does not exist in DB用户不存在。请先通过 RegisterRgbPalm 注册后再执行比对/删除操作
2080017user palm direction does not exist in DB指定手掌方向无掌纹。请检查 PalmDirection 或先完成注册
2080018concurrent operation in DB, please retry数据库并发操作冲突。请退避重试；避免对同一用户并行调用注册/删除
2080020palm capacity quota exceeded平台功能配额超限。请联系技术支持扩容
2080023app does not exist应用不存在。请确认 API Key 所绑定的应用
2080024compare session expired or not exist比对返回的 SessionId 不存在或已过期（有效期 2 小时）。请重新发起 CompareRgbPalm

📌 排障提示

  • 请始终保留 requestId——它是官方技术支持定位问题的关键线索。
  • 1:N 检索返回 2080010、重复注册返回 2080007 均为正常业务结果，不是系统故障。
  • 反复触发容量类错误（2080011、2080014、2080020）或 2060002 时，请携带 requestId 联系官方申请提额或扩容。