# 统一错误码

> 本页返回码主要用于排查、日志和联调定位，不建议把 `resp_code`、HTTP 返回码直接写成订单终态状态机；订单终态仍以 `trans_stat`、`order_stat`、异步通知和主动查询结果为准。

## 网关返回码（HTTP 层）

| 返回码 | 说明 |
|-------|------|
| 200 | 正常访问 |
| 404 | 服务不存在 |
| 412 | 请求体包含非法字符 |
| 500 | 后端服务器错误 |
| 502 | 后端服务调用超时或连接失败 |
| 512 | API 网关 SHUTDOWN |
| 911 | 按 IP/商户 ID/api_key 维度限流 |
| 914 | 按接口总访问数限流 |
| 912 | 安全封禁 |
| 921 | 网关鉴权不通过 |
| 922 | 验签不通过 |
| 923 | 返回结果加签失败 |

## 网关业务返回码

| 返回码 | 说明 |
|-------|------|
| 10000 | 成功调用 |
| 20000 | 服务不可用请联系客服 |
| 20001 | 权限不足 |
| 40001 | 无效参数 |
| 40002 | 验签失败 |

## 业务返回码（线上交易 / 托管支付）

### 通用

| 返回码 | 说明 | 处理建议 |
|-------|------|---------|
| 00000000 | 本次接口处理完成，实际交易结果仍以 `trans_stat` / 查询结果为准 | 继续结合交易状态字段确认终态 |
| 00000100 | 交易正在处理中 | 等待异步通知或轮询查询 |
| 10000000 | 无效参数 | 检查必填字段、格式、长度 |
| 98888888 | 未知系统错误 | 联系汇付技术支持 |
| 99999999 | 系统异常，请稍后重试 | 稍后重试 |

### 商户进件相关

| 返回码 | 说明 | 处理建议 |
|-------|------|---------|
| 00000001 | 基本参数校验失败 | 检查请求参数 |
| 00000103 | 请求系统号无接口访问权限 | 检查 sys_id 权限配置 |
| 00000106 | 商户状态异常 | 联系汇付确认商户状态 |

### 托管支付（hosting）专用

| 返回码 | 说明 | 处理建议 |
|-------|------|---------|
| 99010002 | 预下单请求流水重复 | 使用新的 req_seq_id |
| 99010003 | 交易不存在 | 检查 org_req_date 和 org_req_seq_id |
| 90000000 | 交易受限 / 微信 Scheme 生成失败 | 查看 resp_desc，Scheme 失败需重新配置小程序 |

### 预下单 / 支付相关

| 返回码 | 说明 | 处理建议 |
|-------|------|---------|
| 20000000 | 重复交易 | 使用新的 req_seq_id 重新发起 |
| 20000004 | 交易不存在 | 检查 org_req_date 和 org_req_seq_id |
| 20000005 | 商户不存在 | 检查 huifu_id |
| 20000006 | 商户状态异常 | 联系汇付确认商户状态 |
| 22000000 | 产品配置信息异常 | 检查 product_id 配置 |
| 22000002 | 商户配置信息异常 | 检查 huifu_id 配置 |
| 90000000 | 交易受限 / 单笔金额超限 / 单日金额超限 / 交易存在风险 | 查看 resp_desc 详情，联系客服 |
| 90000001 | 交易存在风险，请稍后再试 | 稍后重试 |

### 关单相关

| 返回码 | 说明 | 处理建议 |
|-------|------|---------|
| 10000015 | 不允许关闭一分钟以内的订单 | 等待 1 分钟后重试 |
| 10000016 | 原订单已为终态 | 订单已完成，无需关单 |
| 10000018 | 关单失败 | 查看 resp_desc 详情 |
| 30000001 | 收银台校验失败（原交易已终态/关单已终态） | 订单已支付走退款流程 |

### 退款相关

| 返回码 | 说明 | 处理建议 |
|-------|------|---------|
| 10000001 | 原交易没有处理完成 | 等待原交易完成 |
| 10000002 | 退款金额大于可退金额 | 检查退款金额 |
| 10000009 | 该交易不支持部分退款 | 只能全额退款 |
| 20000001 | 操作过于频繁 | 稍后重试 |
| 20000003 | 账户已被冻结 | 联系汇付处理 |
| 21000000 | 参数逻辑校验不合法 | 检查参数逻辑关系 |
| 30000000 | 调用收银台退款接口失败 | 稍后重试 |

## 使用边界

- `resp_code`、`resp_desc` 主要用于排查，不直接驱动订单成功/失败终态。
- `00000000` 不等于“这笔订单最终成功”，仍要继续看 `trans_stat`、`order_stat` 或查单结果。
- `00000100` 表示当前接口仍在处理中，应该继续等待异步通知或轮询查询，而不是直接判失败。
- 其余返回码优先结合 `resp_desc`、请求参数、原交易标识和通道场景做定位。