本文档用于指导代理商判断 API 响应。本文中的响应码指响应体 code 字段，不等同于 HTTP 状态码。

1. 响应判断

场景	判断条件	`code` 类型
成功	`code === 200`	整数
失败	`code` 以 `AGENT_` 开头	字符串

成功响应示例：

{
  "code": 200,
  "msg": "success",
  "time": 1720000000,
  "data": {}
}

失败响应示例：

{
  "code": "AGENT_AUTH_40007",
  "msg": "签名无效",
  "detail": "HMAC signature validation failed",
  "request_id": "req_xxx",
  "timestamp": 1720000000,
  "ip": "127.0.0.1"
}

2. 失败错误码

2.1 鉴权与权限

响应码	描述	触发条件
AGENT_AUTH_40001	缺少必要请求头	缺少 AccessKey、时间戳、Nonce 或签名请求头
AGENT_AUTH_40002	请求已过期	请求时间戳与服务器时间相差超过 300 秒
AGENT_AUTH_40003	AccessKey 无效或已禁用	AccessKey 不存在，或对应应用、用户状态异常
AGENT_AUTH_40004	SecretKey 无效	应用未配置有效的 API Secret
AGENT_AUTH_40005	请求重复提交	5 分钟内重复使用同一 Nonce
AGENT_AUTH_40006	IP 不在白名单	生产代理服务启用 IP 白名单且客户端 IP 不匹配
AGENT_AUTH_40007	签名无效	HMAC 签名校验失败
AGENT_SCOPE_40001	当前 API 未授权	AccessKey 的 Scope 不包含当前端点

2.2 参数错误

响应码	描述	触发条件
AGENT_PARAM_40002	参数格式错误	请求参数中包含非法 UTF-8 等格式问题
AGENT_PARAM_40010	Webhook URL 不能为空	设置 Webhook 时未提交 URL
AGENT_PARAM_40011	Webhook URL 格式不正确	Webhook URL 无法通过格式校验
AGENT_PARAM_40012	Webhook 必须使用 HTTPS	Webhook URL 未使用 HTTPS

2.3 风控错误

响应码	描述	触发条件
AGENT_RISK_42901	请求过于频繁	同一 AccessKey 对同一端点超过 10 QPS
AGENT_RISK_40301	访问被风控拦截	生产代理服务命中 IP 黑名单

2.4 业务错误

响应码	描述	触发条件
AGENT_BIZ_30001	持卡人错误	持卡人不存在或不属于当前代理商
AGENT_BIZ_30002	卡号不存在	未查询到指定卡片
AGENT_BIZ_30010	Email already exists	持卡人邮箱已存在
AGENT_BIZ_30011	创建持卡人失败	上游服务未能创建持卡人
AGENT_BIZ_30012	卡片已绑定，请用验证码激活	实体卡已被绑定
AGENT_BIZ_30013	卡状态异常	卡片状态不允许执行当前操作
AGENT_BIZ_30014	卡片刷新异常	刷新卡片信息失败
AGENT_BIZ_30017	System	获取卡片敏感信息等操作发生系统级异常
AGENT_BIZ_30018	转出卡不可与转入卡相符	卡转卡时转出卡与转入卡相同
AGENT_BIZ_30019	转出卡号不存在	卡转卡时未找到转出卡
AGENT_BIZ_30020	转入卡号不存在	卡转卡时未找到转入卡

2.5 系统与兜底错误

响应码	描述	触发条件
AGENT_SYS_50001	系统错误	API 网关发生未捕获异常
AGENT_SYS_50003	第三方服务异常或未分类错误	上游服务失败，或错误消息未匹配到其他固定错误码

AGENT_SYS_50003 是默认兜底码，可能承载参数校验、第三方接口或业务异常。收到此码时必须同时读取 msg 和 detail，不要只根据响应码展示固定文案,必要时可群内联系技术客服

端点响应状态码

1. 响应判断#

2. 失败错误码#

2.1 鉴权与权限#

2.2 参数错误#

2.3 风控错误#

2.4 业务错误#

2.5 系统与兜底错误#

1. 响应判断

2. 失败错误码

2.1 鉴权与权限

2.2 参数错误

2.3 风控错误

2.4 业务错误

2.5 系统与兜底错误