1. 开发指南
OpenAPI
  • 开发指南
    • 开发前必读
    • 申请API Key 与 API Secret
    • 错误码指引
    • 接口签名
    • 接口响应安全校验
    • 多语言
    • 时区相关
    • 更新日志
    • Webhook Beta
    • 业务幂等相关
  • API 使用指南
    • 公共服务
      • 基础配置信息
    • 用户
      • 用户注册
      • 用户列表
      • 用户详情
      • 获取KYC Token
      • 获取KYC H5链接
    • 卡业务
      • 卡渠道列表
      • 实体卡邮寄地址列表
      • 创建实体卡邮寄地址
      • 修改实体卡邮寄地址
      • 删除实体卡邮寄地址
      • 申请卡
      • 激活实体卡
      • 卡列表
      • 卡详情
      • 卡CVV信息
      • 卡交易列表
      • 卡交易详情
      • 重置免密支付金额
      • 重置实体卡 PIN
      • 冻结卡
      • 解冻卡
    • 钱包
      • 钱包列表
      • 链列表
      • 创建钱包链地址
      • 钱包详情
      • 链上收款人列表
      • 链上收款人详情
      • 创建链上收款人
      • 更新链上收款人
      • 删除链上收款人
      • 创建钱包提现交易
      • 取消钱包提现交易
      • 钱包站内划转
      • 钱包划转到卡
      • 钱包交易列表
      • 钱包交易详情
    • 服务调试
      • GET请求调试
      • POST请求调试
  • 数据模型
    • response.Response
  1. 开发指南

错误码指引

概述#

本文档描述了在使用企业KYC/KYB相关API时可能遇到的错误情况。每个错误都包含错误码、错误类型和详细的描述说明。

HTTP 状态码#

状态码含义说明
200成功请求成功处理
400参数错误请求参数不符合要求
401认证失败API签名验证失败或缺少认证信息
403禁止访问权限不足,无法访问该资源
404资源不存在请求的资源或接口不存在
429请求过于频繁短时间内请求次数过多
500系统内部错误服务器内部处理出错

业务错误码列表#

业务幂等相关#

错误码错误类型描述说明
414ErrMissingIdempotencyKeyheader缺少Idempotency-Key幂等KEY业务幂等

认证与安全相关#

错误码错误类型描述说明
100200MissingSignatureHeaders缺少签名头签名认证
100201InvalidTimestamp时间戳格式错误签名认证
100202TimestampExpired时间戳过期签名认证
100203NonceAlreadyUsedNonce 已使用签名认证
100204InvalidApiKey无效的 API Key签名认证
100299InternalError内部错误签名认证

用户注册与登录#

错误码错误类型描述建议处理方式
70003EMAIL_ALREADY_REGISTERED该邮箱地址已被注册请使用其他邮箱或尝试登录
70005ACCOUNT_NOT_EXIST账户不存在请检查账户信息或先进行注册
20001USER_NOT_REGISTERED用户尚未注册请先完成注册流程

验证码相关#

错误码错误类型描述建议处理方式
20021CODE_EXPIRED验证码已过期请重新获取验证码
20022CODE_INVALID验证码无效请检查输入的验证码是否正确

请求参数错误#

错误码错误类型描述建议处理方式
400INVALID_PARAMS请求参数不符合要求请检查请求参数格式和必填项
20022INVALID_CODE验证码格式错误请检查验证码格式

业务处理错误#

错误码描述建议处理方式
100001上传参数不满足接口要求检查入参字段、格式、规则后重新提交
100002无法查询到指定数据确认查询条件、ID、编号等信息是否正确
100003当前手机号已注册更换其他手机号或直接登录已有账号
100004当前邮箱已注册更换其他邮箱或直接登录已有账号
100005验证码不正确核对验证码或重新获取验证码
100006当前用户状态异常,暂时无法登录,请联系您的客户经理联系客户经理核实并解除账号异常限制
100007登录账户和密码不匹配核对账号密码,忘记密码可重置
100008未配置系统默认配置联系技术或管理员完成系统基础配置
100009列表参数查询出的数据长度不一致修正分页、筛选、关联参数后重试
100010提供的凭证不存在或者已经过期重新申请有效凭证后操作
100011Otp验证已绑定,请勿重复绑定无需重复操作,直接使用已绑定OTP验证
100012无法根据账户名称或ID查询到指定的账户信息核对账户ID/名称,确认账户是否存在
100013未知系统异常稍后重试,持续异常请联系技术支持
100014存在正在执行的相同任务,请等待任务执行完毕或5分钟后再试等待任务完成或间隔5分钟后重试
100015验证码发送失败,请稍后再试间隔片刻重新获取验证码
100016您提供的账户信息暂无法查询到指定账户核对账户信息,确认账户状态正常
100017OTP验证码不正确核对OTP动态码,重新输入
100018请先完成实名认证后才可进行操作完善实名认证信息后再执行操作
100019您的信息在等待审核,请勿重复提交耐心等待审核结果,不要重复提交申请
100020暂时无法使用该卡段,请联系您的客户经理联系客户经理确认卡段使用权限
100021当前月份账单您已申请过,请勿重复申请当月无需重复申请,可次月再操作
100022看起来提供了错误的邀请码,请和您的邀请人联系向邀请人索取正确有效邀请码
100023新邮箱验证码不正确核对新邮箱收到的验证码重新填写
100024原邮箱验证码不正确核对原邮箱验证码重新输入
100025您的IP地址已变更,无法验证,请尝试关闭网络代理后重新登录关闭代理/VPN,使用常规网络重新登录
100026此邀请码已存在,请输入新的邀请码更换全新未使用的邀请码
100027您的账户已处于只读状态,无法进行操作,请联系您的客户经理联系客户经理解除只读权限限制
100028机器人通知发送失败无需业务侧处理,可反馈技术排查通知服务
100029当前用户登录次数过多已被锁定,请30分钟后再试等待30分钟锁定自动解除后重试
100030密码不能和前四次密码相同设置全新未使用过的密码
100031OpenAPI权限暂不可用联系管理员开通或恢复OpenAPI权限
100032OpenAPI暂未配置公钥补充配置API公钥后调用接口
100033密码错误核对登录密码,多次错误注意账号锁定
100034账户被清退账号已失效,联系管理员确认账号状态
100035登录环境异常,请重新登录退出账号,刷新环境后重新登录
100036场景名称已存在修改场景名称,保证名称唯一
100037邮箱不存在,请确认大小写是否正确核对邮箱地址大小写及拼写
100038当前客户已经完成实名认证,请勿重复提交无需重复提交实名,直接进行后续操作
100039激活信息有误,请检查核对激活信息、激活码后重新提交
100040请补充收货地址完善收货地址信息后保存提交
100041批量邮寄组id过期重新生成有效邮寄组ID后操作
100042地址信息只能英文,数字, 以及 . , ? : / ( ) ' + - 等符号按规则修改地址内容,剔除非法字符
100043您的实名认证信息不符合平台要求,已停止为您服务联系客服重新提交合规实名资料
100044您的实名认证信息已提交,请勿重复申请等待实名审核,禁止重复发起申请
100045资金密码不正确核对资金密码,忘记可重置密码
100046资金密码不能为空填写正确的资金密码后提交
100047资金密码验证失败次数过多,请24小时后再试等待24小时冷却后重新验证
100048抱歉,该功能暂不支持更换替代功能或咨询平台开放计划
100049不能删除自身账号无权限删除当前登录账号,更换操作账号
100050该用户不是管理员,无法删除使用管理员账号执行删除操作
110001账号已在别处登录下线其他设备,重新登录并保管账号
200001钱包余额不足充值钱包余额后再执行扣款操作
200002储值卡需要设置充值金额填写合法充值金额后提交
200003卡bin不存在或者已不可用,请联系您的客户经理更换有效卡bin或咨询客户经理
200004未提供持卡人ID或者持卡人信息不存在补充正确持卡人ID及信息
200005共享卡无法修改卡余额共享卡不支持该操作,更换卡片类型
200006可用开卡数量不足,请申请开卡上限申请提升开卡额度后继续操作
200007未知开卡异常,请检查持卡人信息是否正确或存在特殊字符清理特殊字符、修正持卡人信息后重试
200008当前卡段不支持OTA场景更换适配OTA场景的卡段
200009批量开卡任务执行中,请等待任务执行完毕后操作等待批量任务结束后再发起新操作
200010预算不存在或状态不可用确认预算ID、启用预算或新建预算
200011金额更新异常,请稍后重试间隔片刻重新操作金额变更
200012要删除的卡余额必须大于等于0结清卡片余额至合规范围再删除
200013要删除的组余额必须大于等于0清空分组余额后再执行删除
200014请先激活预算再进去操作启用对应预算后进行后续操作
200015重复的call id使用唯一不重复的请求ID发起调用
200016卡不存在或者状态不可用核对卡片ID,确认卡片正常启用
200017付出钱包不存在选择已创建且正常的付款钱包
200018接收钱包不存在确认收款钱包已创建且状态正常
200019机构追加手续费至少设置一条,并且不得为0新增合规非0手续费配置项
200020选择的钱包与收款方币种不一致统一收付款钱包币种
200021当前地址与钱包币种不一致匹配地址与钱包对应币种
200022客户开户信息已存在禁止重复开户,使用已有账户
200023持卡人未注册成功先完成持卡人注册再进行业务操作
200024KYT检查失败,风险等级过高完善资料降低风险评级后重试
200025持卡人信息不完整补全持卡人必填信息
200026卡客户不存在核对客户编号,确认客户已开通
200027卡客户状态异常联系客户经理恢复客户正常状态
200028卡客户不属于当前白标账户确认客户归属主体,切换对应账户
200029持卡人注册发生了一些问题,请联系您的客户经理联系客户经理排查注册异常问题
200030无法获取当前卡配置的限额刷新配置或联系技术排查限额配置
200031佣金可提现余额不足等待佣金入账满足提现门槛
200032传入持卡人手机号时,必须传入区号手机号携带国际区号后提交
200033卡已存在,请勿重复创建调用已有卡片,避免重复新建
200034详细地址格式错误:仅允许数字、大/小写字母、空格和短横线(-)精简地址,仅保留合规字符
200035最大消费金额需大于已消费金额调整限额数值,大于当前已用额度
200036卡状态异常,无法查看卡私密信息恢复卡片正常状态后查看详情
200037邮政编码长度必须在 1-10 个字符之间,并且只能包含字母数字字符、连字符 和空格按规则修正邮编格式与长度
200038请求时间已过期校准服务器本地时间,重新生成请求
200039未开启openapi权限申请开通对应OpenAPI访问权限
200040数据解析失败检查请求参数格式、编码、JSON合法性
200041当前卡bin开卡数量已达上限,请选择其他卡bin更换其他卡bin或申请提升限额
200051当前卡不支持设置周限额更换卡片类型或使用其他周期限额
200055CVV不可用:该卡无余额或已冻结。充值余额或解除卡片冻结状态
200061开卡费用扣款失败,请检查账户余额是否充足补足账户余额后重新发起开卡
200065储值卡最低充值额度为10USD充值金额不低于最低限额
20066储值卡充值金额需在指定区间内按区间范围填写充值金额
20067储值卡提现金额需在指定区间内调整提现金额至规定范围
20068卡最低保留金额不足预留规定最低余额后再操作
200800批准正常业务结果,无需处理
200801不承兑交易拒绝,更换支付方式重试
200802账户已关闭账户已注销,更换有效账户
200803资金不足充值资金后重新发起交易
200804卡片已过期更换有效卡片进行交易
200805交易不被持卡人允许确认卡片交易权限配置
200806交易不被终端允许更换交易终端或交易场景
200807超出取款金额限制降低取款金额至限额内
200808受限卡(例如:卡片在该地区或国家无效)更换不受地域限制的卡片
200809安全违规排查操作环境,解除安全限制
200810超出取款频率限制降低操作频次,间隔时段重试
200811验证数据失败核对交易验证信息重新提交
200812卡片未激活先完成卡片激活再使用
200813无法路由交易更换交易渠道或稍后重试
200814系统故障稍后重试,持续异常联系技术
200815SCA要求,卡片形式因素完成安全认证后继续交易
200816CVV2验证失败核对卡片CVV码重新输入
20003创建账户失败请稍后重试或联系技术支持
20004创建用户失败请稍后重试或联系技术支持
20009签名失败,时间戳过期校准设备本地时间,重新发起请求
20012签名验证失败检查API密钥、签名算法和时间戳
20100注册尝试次数过多,请5分钟后再试请等待锁定解除后再尝试
201001必须提供"城市"补充城市信息后提交
201002必须提供"详细地址"填写完整详细地址
201003提供的邮箱或手机号已关联持卡人使用未绑定的联系方式或更换持卡人
201004超过每月开卡数量限制次月再操作或申请提升月度额度
201005必须是有效的邮政编码修正邮编,保证格式合规有效
201006first_name仅允许指定合法字符修改姓名字段,剔除非法符号
201007必须是有效的电话号码核对手机号格式、区号、位数
201008必须是有效的州代码填写合规标准州编码
201009邮箱是必填项补充邮箱地址后提交
201010邮编是必填项填写完整邮政编码
201011该用户已经在渠道注册过直接登录已有渠道账号
210001交易已上链,无法取消链上交易不可逆,确认后再提交
210002交易不存在或者无权限查看核对交易单号,确认访问权限
210003交易执行已失败,无法取消直接发起新的正常交易
210004交易不存在,用户已取消该笔交易或者该笔交易无法审核确认交易状态,重新下单
210005交易已经成功,无法终止交易已完成,不可撤回
210006渠道不正确切换对应业务合法渠道
210007交易已经完成无需重复操作,查看交易记录即可
210008卡片充值系统异常,请稍后再试或联系客户经理稍后重试,异常持续联系客户经理
210429操作过于频繁,请稍后再试降低操作频率,间隔冷却后重试
210430卡授权处理中,无需重复提交等待授权结果,禁止重复请求
210431卡片状态不正常,无法进行授权恢复卡片正常状态后授权
210432卡片渠道不匹配选择卡片对应渠道发起操作
300001您的内转钱包已创建成功,请勿重复申请使用已有钱包,禁止重复创建
300002暂时无法满足您的银行账户申请,请联系您的客户经理联系客户经理排查开户驳回原因
300003要修改的银行账号名称和原名称一致调整名称内容后再保存修改
300004您的账户暂无可用的银行账户先申请绑定有效银行账户
300005银行账户关联信息不存在重新绑定合法银行账户
300006当前账户有申请中的VA,请先完成VA申请等待在途申请办结后再操作
300007当前账户有相同渠道、相同货币的VA避免重复创建同渠道同币种账户
310000钱包总余额需满足最低额度要求充值钱包达到最低门槛金额
400001参数错误校验接口入参类型、必填项、格式
400002钱包不存在新建对应币种钱包或选择正确钱包
400003币种不在支持范围内更换平台支持的币种操作
400004cw kyb 状态不正确完成合规认证,更新账号状态
400005当前钱包的链地址已存在避免重复生成同链地址
400006当前链已暂停支持切换其他正常公链进行操作
400007KYT检查存在,风险等级过高完成风控核验,降低账号风险
400008付款钱包币种和提现钱包币种不一致统一收提钱包币种
400009对方不存在此币种钱包告知收款方开通对应币种钱包
400010请选择其它账户更换合规可用业务账户
400011请提供所有必需的转账信息,包括币种和金额补全转账必填字段后提交
500001提供的扣款钱包暂不支持付款更换支持付款的钱包账户
500002付款的钱包不存在或不可用选择正常可用的付款钱包
500003提现地址已存在使用已有提现地址,禁止重复添加
500004暂只支持同币种付款保证收支币种一致
500005收款人信息不正确核对收款人账号、姓名、地址
500006换汇订单未完成等待换汇订单办结后再操作
500007暂不支持此渠道付款,请选择其他渠道切换平台支持的付款渠道
510001付款方式对应的国家错误匹配付款方式与所属国家
510002付款方式对应的货币错误选择对应货币的支付方式
510003付款金额低于手续费提高付款金额,覆盖手续费用
510004收款人货币不支持更换双方共同支持的币种
510005付款证明材料不完整补齐付款凭证、单据等资料
600001此货币暂不支持转换更换可兑换币种
600002此目标货币暂不支持选择平台支持的目标币种
600003货币重复选择两种不同币种进行兑换
600004汇率获取失败稍后重试,网络异常可检查网络
600005汇率已发生变更,请重新确认刷新最新汇率后再次提交
610003上传文件到oss失败检查文件大小、格式、网络后重试
610004上传文件到oss超时优化网络或压缩文件重新上传
610005上传文件到oss异常稍后重试,持续异常联系技术
610006object获取失败核对文件资源标识,重新拉取资源
610007object上传到渠道失败更换上传渠道或压缩文件重试
700001当前邮箱已注册更换未注册邮箱或登录原有账号
700002当前API账户没有创建个人实体的权限申请开通实体创建权限
700003实体不存在或者不属于当前API账户核对实体ID,切换归属账号
701001API密钥已存在,请勿重复创建使用已生成的API密钥
701002未创建API密钥,请先创建API密钥先生成合法API密钥再调用接口
701003无可更新内容数据无变更,无需提交修改
701004未找到webhook日志核对回调地址、请求时间范围
701005该类型不允许重试废弃原请求,重新发起全新操作
701006公钥不符合要求,请按照要求移除开始和结束的标识符清理公钥头尾标识,仅保留密钥内容
701007api权限不存在为账号分配对应API接口权限
800001部门名称已存在修改部门名称保证唯一
800002菜单ID列表不正确核对菜单ID,修正关联列表
800003成员不存在确认员工账号是否有效
800007部门成员不存在核对部门人员名单后操作
800008提供的部门无法查询到确认部门编号、名称无误
800009不能删除当前登录成员切换管理员账号操作删除
800010不能删除无上级部门的部门调整组织架构后再删除
800011无法删除管理员用户管理员账号禁止直接删除
800012当前角色有配置用户,无法删除先解绑角色关联用户再删除
800013部门下有成员,暂时不能删除清空部门人员后执行删除
800014当前部门存在下级部门,不能直接删除先删除下级部门再操作上级
900001订单创建失败核对订单参数、库存、余额后重试
900002参数格式错误或参数传输不符合规则统一参数格式、编码、提交规范
900003没有收单权限申请开通对应业务收单权限
900004创建时间范围超出最大限制缩短查询/创建时间区间
900005互斥定时任务导致的错误,无需处理系统自动规避,无需人工干预
900006待提现币种钱包余额不足或不存在充值或新建对应币种钱包
900010查询支付订单不存在核对订单号、交易时间范围
900011查询支付订单已过期订单已失效,重新下单
900012渠道与币种不匹配,请检查匹配渠道与对应结算币种
900013子订单创建失败检查主订单参数,重新拆分下单
910001金额必须大于0输入大于0的合法金额
910002金额必须大于或等于0.1调整金额至最低准入值以上
920001询价已过期,请重试刷新询价价格后重新交易
920002钱包余额不足充值钱包余额后操作
920003非法金额输入正数、合规范围内金额
920004接口异常,请稍后重试短暂等待后重新调用接口
920005币种不能相同选择两种不同币种进行兑换划转
920010不支持的币种选用平台已开放币种
920011价格已过期刷新最新报价后提交
920012参数不一致统一前后端、接口传参字段内容
920013余额不足补足账户可用余额
920014闪兑系统繁忙错峰时段重新发起闪兑
920015分配地址中,请稍后再试等待地址分配完成后操作
920016划转中,请勿重复提交等待划转结果,禁止重复请求
920017划转失败,请稍后再试核查余额与权限后重新划转
920018可用佣金不足以提现累计佣金达到提现门槛
920019用户不存在核对用户ID、账号,确认已注册
920020收款人未完成 KYC提醒收款方完成合规认证
920030该手机号已被注册,请使用其他手机号更换全新未注册手机号
920031验证码输入错误,请重新输入重新获取并填写正确验证码
920032验证失败,请重试核对验证信息,再次提交
920033最低提现金额不足提高提现金额至平台最低标准
920034转账金额小于要求金额上调转账金额至合规下限
920035转账金额有误,请重新输入检查数值、小数点后重新填写
920036用户不存在或已被禁用确认用户状态,启用或更换账号
920037汇率暂时无法获取,请稍后重试等待汇率服务恢复后操作
920038暂时不支持该币种, 请使用其他币种切换平台支持的流通币种
920039暂时不支持多张卡申请单次仅提交单张卡片申请
920040该用户未完成KYC认证,暂时无法进行操作完成KYC实名认证后解锁功能
920041该记录不存在核对查询条件、单据编号
920042该操作执行失败,请联系客服联系平台客服排查操作异常
920043转账金额超出规定区间在指定金额区间内填写数值
920044只允许USDT 或者 USDC 进行转账切换为指定稳定币币种转账
921039您有审批中的卡,请勿重复申请等待在途审批完成后再申请
921040免密支付金额不在范围内调整金额至免密限额区间
921041免密支付金额格式错误修正金额数字格式、小数点
921042该卡暂不支持激活更换卡片或联系客服解锁激活
921043激活码错误核对正版激活码重新输入
921044PIN码过于简单,请勿输入连续重复的数字设置复杂度合规的6位PIN码
921045PIN码格式错误,必须是6位纯数字严格按照6位纯数字设置PIN码
921046PIN码不能包含3个及以上连续相同数字规避三连重复数字组合
921047PIN码不能是连续升序或降序数字避免顺子类弱密码组合
921048PIN码不能是重复的3位数字段不使用三位循环组合密码
921049PIN码不能是重复的2位数字段不使用两位循环组合密码

全局错误#

错误码错误类型描述建议处理方式
10001SYSTEM_ERROR系统内部处理错误请稍后重试,如果问题持续请联系技术支持
10002REQUEST_ERROR你的错误请求过于频繁,请稍后再试请检查请求参数或者签名之后再试,如果问题持续请联系技术支持
10003REQUEST_ERROR当前请求处理中,请勿重复提交业务幂等处理统一错误提示,如果问题持续请联系技术支持

错误响应格式#

所有错误响应都遵循以下JSON格式:
{
    "code": 错误码,
    "message": "错误描述信息",
    "timestamp": 时间戳
}

成功响应示例#

{
    "code": 0,
    "message": "success",
    "timestamp": 1770359241378
}

错误响应示例#

参数错误:
{
    "code": 400,
    "message": "invalid parameters",
    "timestamp": 1770359241378
}
认证失败:
{
    "code": 401,
    "message": "unauthorized",
    "timestamp": 1770359241378
}
签名错误:
{
    "code": 20012,
    "type": "INVALID_SIGNATURE",
    "message": "Invalid signature"
}
邮箱已被注册:
{
    "code": 70003,
    "message": "this email is already registered",
    "timestamp": 1770359241378
}

错误处理建议#

1. 客户端处理流程#

1.
收到错误响应时,首先检查HTTP状态码
2.
解析业务错误码,根据错误类型采取相应措施
3.
向用户展示友好提示,避免直接显示技术错误信息
4.
记录错误日志,便于问题排查

2. 常见错误处理#

错误场景处理建议
400 参数错误检查请求参数格式、必填项和数据类型
401 认证失败检查API密钥、签名和时间戳是否正确
403 权限不足联系管理员确认账户权限
429 请求频繁降低请求频率,实现请求限流
500 系统错误稍后重试,如持续失败联系技术支持

3. 重试策略建议#

4xx错误(除429外):修正请求后重试
429错误:等待指定时间后重试(建议指数退避)
5xx错误:间隔3-5秒后重试,最多3次

API使用注意事项#

请求频率限制#

待定

认证要求#

所有API请求必须包含有效的API密钥等签名必要信息

数据格式要求#

请求和响应均使用JSON格式
时间戳使用秒级Unix时间戳

技术支持#

如果您遇到本文档未涵盖的错误,或对错误处理有疑问:
1.
检查API文档:确保按照最新文档使用API
2.
查看错误日志:记录完整的请求和响应信息
3.
联系技术支持:提供以下信息:
错误码和错误信息
请求时间戳
相关请求参数(脱敏后)
您的账户ID或API密钥(前4位)

修改于 2026-04-24 08:38:43
上一页
申请API Key 与 API Secret
下一页
接口签名
Built with