Documentation Index
Fetch the complete documentation index at: https://docs.gate.com/llms.txt
Use this file to discover all available pages before exploring further.
通用错误码
| 错误码 | 说明 | 适用 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 及以上版本
相关文档
