> ## 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 | 签名验证失败            | 通用                                                          | 检查签名算法、签名字符串和签名密钥. 见 [认证与安全](/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](/essentials/version/100/cn/inflow/payment/payment) | 确认订单是否已过期                                                                      |
| 400621 | 支付金额不正确           | [支付 API](/essentials/version/100/cn/inflow/payment/payment) | 检查请求金额                                                                         |
| 400622 | 因汇率波动导致兑换失败       | 报价 / 兑换类 API                                                | 如业务流程允许，可重试                                                                    |
| 400624 | 回调 URL 非法         | 订单创建类 API                                                   | 检查回调 URL 是否有效. 见 [通知与回调](/essentials/version/100/cn/common/notification)       |

***

## 批量出款错误码

有关详细出金错误处理，请参见 [出金](/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 | 签名验证失败   | 二维码支付  | 检查商户签名是否正确. 见 [认证与安全](/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 支付 | 检查商户签名是否正确. 见 [认证与安全](/essentials/version/100/cn/common/authentication) |

***

## 最佳实践

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

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

**推荐做法：**

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

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

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

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

### 退款确认

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

**必需实践：**

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

### 安全最佳实践

**认证与签名验证**

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

**密钥管理**

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

**请求校验**

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

***

## 相关文档

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