# 响应与错误码

> 通用响应结构、错误码，以及幂等、金额与状态的处理建议。

## 通用响应结构

所有商户 API 的业务响应统一格式：

```json
{
  "code": 0,
  "msg": "success",
  "data": {}
}
```

规则：

- `code = 0` 表示成功
- `code != 0` 表示失败
- `msg` 为原因说明。失败信息通常以 `|` 加一个固定的键结尾（例如 `Order not found|orderNotFound`）；请按错误码或该键判断，不要按文本判断
- `data` 成功时为业务对象，失败时不返回
- 所有带签名的响应（包括错误）HTTP 状态码均为 `200`。只有鉴权错误（`401` / `403`）与下单频率限制（`429`，见 [重要说明](https://www.hansapay.io/docs/zh/what-to-expect)）使用各自的 HTTP 状态码

常见错误码：

| code | 含义 |
| --- | --- |
| `400` | 请求格式错误 |
| `401` | 未授权 |
| `403` | 无权访问 |
| `422` | 业务参数校验失败，包括 `merchant_order_no` / `merchant_refund_no` 重复 |
| `500` | 系统内部错误 |
| `1001` | 商户账户已停用 |
| `2002` | 订单不存在 |
| `2006` | 代收金额不满足通道限制 |
| `3003` | 未开通该支付方式或该支付方式目前不可用 |
| `4001` | 下单过于频繁（HTTP `429`），请稍后重试 |
| `5001` | 代付单号重复 |
| `5002` | 代付订单不存在 |
| `5004` | 代付余额不足 |
| `5007` | 代付方式不可用 |
| `5008` | 代付金额不满足通道限制 |

## 接入建议

### 幂等处理

- 按 `merchant_order_no`、`merchant_refund_no`、`merchant_payout_no` 做幂等
- 通知处理同样需要幂等
- 若多次收到同一通知，确认订单已处理后返回 `success`
- 重复的 `merchant_order_no` 或 `merchant_refund_no` 会以 `code=422` 拒绝；HansaPay 不会返回原响应。若创建请求超时，请先按你的单号查询，再使用新单号重试
- HansaPay 已记录后失败的请求（例如卡被拒）同样占用其单号
- `merchant_order_no` 与 `merchant_refund_no` 共用同一命名空间：不要把退款单号用作订单号

### 金额处理

- 请求金额一律使用字符串
- 不要用浮点数计算金额
- 商户侧使用 decimal 库

### 状态处理

- 以异步通知作为最终依据
- 查询接口用于对账与兜底
- 即使直连下单返回 `SUCCESS`，也应保留通知处理
- 履约逻辑中不要把卡支付的 `FAILED` 视为终态；见 [查询支付订单](https://www.hansapay.io/docs/zh/payments#query-payment-order)
