> ## 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.

# 错误

> 本文档介绍 GatePay API 的常见错误码，以及错误处理、回调处理和异步流程的推荐实践。

## 通用错误码

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

***

## 批量出款错误码

有关详细出金错误处理，请参见 [出金](/global/essentials/version/100/cn/outflow/payout)。

| 错误码 | 说明 | 适用 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 | 签名验证失败 | 二维码支付 | 检查商户签名是否正确. 见 [认证与安全](/global/essentials/version/100/cn/common/authentication) |
| 400003 | 请求时间戳已过期 | 二维码支付 | 检查时间戳请求头 |
| 400007 | 不支持的媒体类型 | 二维码支付 | 检查 API Content-Type |
| 400603 | 订单超时 | 二维码支付 | 确认订单是否已过期 |
| 400621 | 支付金额不正确 | 二维码支付 | 检查请求金额 |
| 400620 | 支付订单重复 | 二维码支付 | 检查商户订单号是否重复提交 |
| 500008 | 商户不存在 | 二维码支付 | 检查商户 ID 是否正确 |
| 500100 | 支付二维码已过期 | 二维码支付 | 创建新订单以生成新的二维码 |
| 500101 | 二维码支付重复 | 二维码支付 | 核验订单状态 |

***

## Web 支付错误码

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

***

## 最佳实践

### 回调与查询兜底策略

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

**推荐做法：**

1. 将**回调**作为主要通知机制，接入方式可参考 [通知与回调](/global/essentials/version/100/cn/common/notification)
2. 处理任何回调前先**实现签名验证**，具体规则可参考 [认证与安全](/global/essentials/version/100/cn/common/authentication)
3. 使用**幂等性**安全处理重复回调
4. 处理前**持久化存储通知**
5. 为回调处理**实现状态机控制**

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

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

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

### 退款确认

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

**必需实践：**

* 通过退款查询 API 或退款回调确认最终退款结果，退款回调详情可参考 [支付](/global/essentials/version/100/cn/inflow/payment/payment)
* 使用“回调优先、查询兜底”模式验证退款完成状态
* 不要仅根据 API 响应就认为退款已完成

### 安全最佳实践

**认证与签名验证**

* 处理前始终验证回调签名，具体规则可参考 [认证与安全](/global/essentials/version/100/cn/common/authentication)
* 如果签名验证失败，不要在回调响应中返回 `SUCCESS`
* 检查请求时间戳以防止重放攻击

**密钥管理**

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

**请求校验**

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

***

## 相关文档

* [支付](/global/essentials/version/100/cn/inflow/payment/payment) ： 支付处理与退款处理
* [出金](/global/essentials/version/100/cn/outflow/payout) ： 出金错误码与处理
* [通知与回调](/global/essentials/version/100/cn/common/notification) ： 回调接入模式
* [认证与安全](/global/essentials/version/100/cn/common/authentication) ： 签名验证与安全实践


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.