错误 - Gate Pay DOCS

通用错误码

错误码	说明	适用 API	处理方式
400001	请求参数非法	通用	检查请求参数是否有效
400002	签名验证失败	通用	检查签名算法、签名字符串和签名密钥. 见认证与安全
400003	请求时间戳已过期	通用	检查时间戳请求头
400007	不支持的 Content-Type	通用	检查 Content-Type 是否符合 API 要求
400020	nonce 非法	通用	检查 X-GatePay-Nonce 是否为空或格式错误
400201	商户订单号重复	创建订单相关 API	检查是否重复提交了相同商户订单号
400202	订单不存在	查询类 API	检查订单号是否正确
400204	订单状态非法	订单操作类 API	检查订单是否已过期、取消或关闭
400603	订单超时	支付 API	确认订单是否已过期
400621	支付金额不正确	支付 API	检查请求金额
400622	因汇率波动导致兑换失败	报价 / 兑换类 API	如业务流程允许，可重试
400624	回调 URL 非法	订单创建类 API	检查回调 URL 是否有效. 见通知与回调

批量出款错误码

有关详细出金错误处理，请参见出金。

错误码	说明	适用 API	处理方式
550233	余额不足	批量出款	检查可用余额
550234	备注过长	批量出款	检查备注长度
550235	金额精度超过允许范围	批量出款	检查金额精度
550238	子订单数量过多	批量出款	检查子订单数量
550239	amount 字段缺失	批量出款	提供 amount 字段
550240	currency 字段缺失	批量出款	提供 currency 字段
550241	address 字段缺失	批量出款	提供 address 字段
550242	chain 字段缺失	批量出款	提供 chain 字段
550245	batch_id 已存在	批量出款	使用新的 batch_id，或按幂等请求处理
550249	batch_id 或提现订单 ID 非法	批量出款	检查字段格式

资金流水查询错误码

错误码	说明	适用 API	处理方式
5504060	订单类型参数非法 (1=商户订单号, 2=GatePay 订单号, 3=资金账本数字)	资金账本查询	修正订单类型参数
5504061	查询条数超过限制 (≤ 500)	资金账本查询	减少单次请求的记录数量

二维码支付错误码

错误码	说明	适用 API	处理方式
400000	请求格式非法	二维码支付	检查请求数据格式
400002	签名验证失败	二维码支付	检查商户签名是否正确. 见认证与安全
400003	请求时间戳已过期	二维码支付	检查时间戳请求头
400007	不支持的媒体类型	二维码支付	检查 API Content-Type
400603	订单超时	二维码支付	确认订单是否已过期
400621	支付金额不正确	二维码支付	检查请求金额
400620	支付订单重复	二维码支付	检查商户订单号是否重复提交
500008	商户不存在	二维码支付	检查商户 ID 是否正确
500100	支付二维码已过期	二维码支付	创建新订单以生成新的二维码
500101	二维码支付重复	二维码支付	核验订单状态

Web 支付错误码

错误码	说明	适用 API	处理方式
300000	系统错误	Web 支付	使用相同参数重试
300001	系统错误	Web 支付	使用相同参数重试
400000	未知错误	Web 支付	记录请求、重试或联系支持
400001	请求参数格式非法	Web 支付	检查请求参数和数据格式
400002	签名验证失败	Web 支付	检查商户签名是否正确. 见认证与安全

最佳实践

回调与查询兜底策略

使用“回调优先、查询兜底”的确认模型，可靠管理订单状态： 推荐做法：

将回调作为主要通知机制，接入方式可参考通知与回调
处理任何回调前先实现签名验证，具体规则可参考认证与安全
使用幂等性安全处理重复回调
处理前持久化存储通知
为回调处理实现状态机控制

查询兜底策略: 如果回调缺失或延迟，请使用渐进式退避进行状态查询：

5 秒
10 秒
30 秒
1 分钟
3 分钟
5 分钟

该策略可避免对 API 造成过大压力，同时确保及时确认订单。

退款确认

退款是异步操作。退款 API 成功响应仅表示请求已受理，并不确认退款已实际处理完成。 必需实践：

通过退款查询 API 或退款回调确认最终退款结果，退款回调详情可参考支付
使用“回调优先、查询兜底”模式验证退款完成状态
不要仅根据 API 响应就认为退款已完成

安全最佳实践

认证与签名验证

处理前始终验证回调签名，具体规则可参考认证与安全
如果签名验证失败，不要在回调响应中返回 SUCCESS
检查请求时间戳以防止重放攻击

密钥管理

不要在客户端应用中暴露服务端签名密钥或凭证
使用环境变量或安全密钥库妥善存储商户密钥
定期轮换签名密钥，并为测试环境和生产环境维护独立密钥

请求校验

处理前验证所有请求参数
检查 Content-Type 请求头并确保其符合 API 要求
所有 API 通信均使用 HTTPS 与 TLS 1.2 及以上版本

相关文档

支付：支付处理与退款处理
出金：出金错误码与处理
通知与回调：回调接入模式
认证与安全：签名验证与安全实践

⌘I