> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout 错误码与重试

> Payout 的错误码集合与支付的不同：每个 A/B/C/D/E 码对 Payout 意味着什么、哪四个码可以安全重试、哪些码意味着要修改请求、为什么 A0003 携带字段名，以及 B 前缀的码实际指的是什么。

Payout 返回自己的一套错误码。前缀看起来和支付的一样，有几个码也重叠，但**含义并不相同**——
处理 Payout 响应时，请读本页的表格而不是
[支付错误码](/docs/zh/developer-docs/tools-and-references/developer-tools/error-codes)。每个请求
字段该填什么，见
[Payout 请求字段指南](/docs/zh/support/payout-request-field-guide)。

## 这些前缀是什么意思？

| 前缀 | 类别 | 如何处理 |
| - | - | - |
| `A` | 与你或你的请求有关 | 修正请求或你的配置；不要原样重试 |
| `B` | 与**收款人**有关 | 修正收款人信息，或请收款人修正他们的账户 |
| `C` | Waffo 或 Payout 路由 | 有些可重试；见表格 |
| `D` | 出于风控原因被拒绝 | 不要重试；联系 Waffo |
| `E` | 结果未知 | **绝不要当作失败处理。** 持续查询直到得到终态 |

## 完整的 Payout 码表

### A——商户与请求

| 码 | 消息 | HTTP | 怎么做 |
| - | - | - | - |
| `A0001` | Invalid Api secret key | 401 | 检查你用于签名的 key |
| `A0002` | Invalid signature | 401 | 检查你的签名实现 |
| `A0003` | Parameter validation failed | 400 | 修正指名的字段——见下文 |
| `A0004` | Permission denied | 401 | 你的凭证或调用 IP 不被允许执行此操作 |
| `A0005` | Merchant limit exceeded | 400 | 触及了账户级限制 |
| `A0006` | Merchant status abnormal | 400 | 见下文 |
| `A0007` | Payout currency is not supported | 400 | 该币种不在你的任何 Payout 协议中 |
| `A0008` | Payout limit exceeded — amount should be within the range | 400 | 见下文 |
| `A0009` | Order does not exist | 400 | 查询时：该 id 无法解析为你的某笔订单 |
| `A0010` | Operation not allowed in merchant contract | 400 | 见下文 |
| `A0011` | Idempotent param mismatch error | 400 | 相同的 `payoutRequestId`，不同的金额 / 币种 / 账户 |
| `A0012` | Merchant account insufficient balance | 400 | 出资币种的已结算余额不足 |
| `A0013` | Too many requests, please try again later | 400 | 同一 `payoutRequestId` 的重复创建正在处理中——**可重试** |

**Payout 没有 `A0014`。** 金额、币种和收款人账户都与原始请求一致的重复创建，会返回
**普通的成功码**并附带原始订单的数据，而不是一个独立的幂等码。请通过比较返回的
`payoutOrderId` 与你已持有的那个来检测，而不是寻找特殊的码。

### B——收款人

| 码 | 消息 | HTTP | 它实际指的是什么 |
| - | - | - | - |
| `B0001` | User status abnormal | 400 | **收款人的**收款账户不处于可用状态 |
| `B0002` | User limit exceeded | 400 | 触及了**收款人**一侧的限制 |
| `B0003` | User does not exist | 400 | 找不到**收款人的**账户 |
| `B0004` | User info does not match | 400 | 收款人姓名或账户信息与收款账户不匹配 |

**这里的"User"指的是收款人，不是你平台的用户，也不是你。** 这是 Payout 码集合中最常被
误读的部分。`B0001` 或 `B0003` 是关于你指定的收款账户的消息——一个已关闭的钱包、一个
错误的账号、一个从未存在过的账户——修复点在收款人的信息或收款人本身，永远不在你的商户配置。

`B0004` 是姓名或账户不匹配浮现的地方；匹配规则见
[Payout 请求字段指南](/docs/zh/support/payout-request-field-guide)。

### C——Waffo 与 Payout 路由

| 码 | 消息 | HTTP | 可重试 |
| - | - | - | - |
| `C0001` | System error | 500 | **是** |
| `C0002` | Invalid merchant contract | 500 | 否——见下文 |
| `C0003` | Order info mismatch error | 500 | 否 |
| `C0004` | Payout channel rejection | 503 | 否——收款侧拒绝了它 |
| `C0005` | Payout channel error | 503 | **是** |
| `C0006` | Payout channel submit error, please try again later | 500 | 当作未知处理——查询 |
| `C0007` | Payout channel fx submit error, please try again later | 500 | 当作未知处理——查询 |

`C0002` 因为 `C` 前缀和 500 看起来像系统错误，但它是配置问题：没有 Payout 协议匹配你的
请求，或者匹配的安排没有定义费用。你在请求体中改任何东西都无法修复它——检查 Portal 中的
Service → Payout 是否有覆盖该国家、货币对和方式的生效协议，如果有但 Payout 仍然失败，
请向 Waffo 反馈。

### D 与 E

| 码 | 消息 | HTTP | 怎么做 |
| - | - | - | - |
| `D0001` | Risk rejection | 406 | 不要重试。联系 Waffo——原因不会在响应中返回 |
| `E0001` | Unknown status | 500 | 持续调用 `/api/v1/payout/inquiry` 直到得到 `SUCCESS` 或 `FAILURE` |

## 哪些码可以原样重试，哪些需要修改请求？

提交时被归类为可重试的恰好有四个码：

| 可重试 | 码 |
| - | - |
| ✅ | `A0013`——重复创建正在处理中 |
| ✅ | `C0001`——系统错误 |
| ✅ | `C0005`——Payout 渠道错误 |
| ✅ | `E0001`——未知状态 |

其他所有码都意味着 Payout 原样不变不会成功。对这四个码用**相同的** `payoutRequestId`
重试——这正是幂等性的用途，也是避免创建第二笔 Payout 的唯一方法。带退避地重试，
并在两次尝试之间查询。

对其余的码，划分如下：

| 类别 | 码 | 修复方式 |
| - | - | - |
| 修改请求 | `A0003`、`A0007`、`A0008`、`A0011`、`B0001`–`B0004` | 更正字段、金额、币种或收款人，然后用**新的** `payoutRequestId` 发送 |
| 修改你的配置或状态 | `A0005`、`A0006`、`A0010`、`A0012`、`C0002` | 余额、协议或账户状态——问题不在请求 |
| 修复你的集成 | `A0001`、`A0002`、`A0004` | 凭证、签名、IP 白名单 |
| 停下来询问 | `C0004`、`D0001` | 已被拒绝；重试没有任何作用 |
| 暂不判断 | `C0006`、`C0007`、`E0001` | 结果未确定——查询 |

## `A0003` 告诉我校验失败了。我能知道是哪个字段吗？

可以，而且 `A0003` 是**唯一**携带详情的 Payout 码。它的消息以通用文本返回，后面跟着
括号中的具体信息：

```
Parameter validation failed(payoutInfo.payoutMethodProperty.bankCode: invalid bankCode)
```

详情以字段路径为键——`payeeInfo.payeeBirthDay`、`payoutInfo.payoutMethodName`、
`payoutAmount` 等——并且可能出现多个字段。其他所有码只返回其标准消息，所以不要构建
期望从 `A0003` 以外的任何码获取详情的解析逻辑。

## 我收到了 `A0008`。是单笔 Payout 太大，还是我用完了额度？

Payout 上的 `A0008` 是关于**单笔 Payout 金额**落在该通道允许范围之外——低于最小值或高于
最大值。两个边界都来自你的 Payout 协议，并以出资币种显示为 Portal 中 Service → Payout
页面上的 **Minimum Amount** 和 **Maximum Amount**。请对照你所用国家、货币对和方式对应
的那一行检查金额。

另外两种情况是不同的码，你可以据此区分：

| 码 | 含义 |
| - | - |
| `A0008` | 这笔 Payout 的金额超出该通道的允许范围 |
| `A0005` | 超出了账户级限制 |
| `A0012` | 你在出资币种的已结算余额不足以覆盖该 Payout 及其费用 |
| `B0002` | 收款人一侧的限制，不是你的 |

余额耗尽是 `A0012`，不是 `A0008`——哪个账户被扣款见
[Payout 钱包与覆盖范围](/docs/zh/support/payout-wallet-and-coverage-faq)。

## `A0010` "Operation not allowed in merchant contract" 在实践中是什么意思？

意思是你请求的 Payout 不在你任何一个生效的 Payout 安排的覆盖范围内。常见原因，
按值得检查的顺序：

1. **该组合没有协议。** 国家、货币对、方式类型和方式都必须与 Service → Payout 上的
   某一行匹配。
2. **协议不是 Active。** 只有 *Active* 才能交易；*Initial*、*Suspended* 和
   *Terminated* 都不能。
3. **协议已失效。** 它的 Validity Period 有结束日期；过了之后协议停止交易。
4. **`payeeType` 不是该安排接受的类型。** 一个安排可以面向个人、面向公司，或两者都可以。
5. **`productName` 不是你拥有的。** 无法识别的产品会在该字段上以 `A0003` 被拒绝；
   你拥有但在该通道上未签约的产品则落到这里。

请求体中没有任何东西能修复以上任何一条。先把你的请求与 Service → Payout 的那一行对比，
然后向 Waffo 反馈。

## Payout 协议会过期吗？在哪里能看到过期时间？

会——Service → Payout 上的每一行都带有一个有开始和结束的 **Validity Period**，以及一个
**Status**。协议已过结束日期的通道上的 Payout，会以 `A0010` / `C0002` 这一族被拒绝，
而不是一个专门的过期码，所以当一条原本可用的通道停止工作时，Validity Period 是要检查的
字段。请在失效前审查它；续期是一次合约对话，不是 Portal 操作。

## `A0006` "Merchant status abnormal"——我被暂停了吗？

`A0006` 意味着你的商户账户无法被解析为可用于这笔 Payout——要么用你发送的 id 找不到账户，
要么其状态不允许交易。它不是 Payout 专有的，也不会说明**为什么**。先检查请求中的
`merchantInfo.merchantId`——错误或输错的 id 会产生同样的码——然后联系 Waffo，因为响应
有意不携带原因。

## 创建调用超时了，我不知道它是否成功。重试还是查询？

**查询。** 一次你没有收到响应的创建可能已经成功。用你的 `payoutRequestId` 调用
`/api/v1/payout/inquiry`：

| 查询结果 | 含义 |
| - | - |
| 返回了一笔订单 | 创建成功了。根据它的状态处理。 |
| `A0009`（order does not exist） | 创建没有落地。可以安全地再发一次——相同的 `payoutRequestId`。 |

重新发送创建也是安全的，因为 `payoutRequestId` 是幂等的：完全相同的重发会返回原始订单，
而不是创建第二笔 Payout。**不**安全的是在超时后用一个*新的* `payoutRequestId` 发送同一笔
Payout——重复 Payout 就是这样产生的。

## 出于风控原因被拒绝的 Payout 可以申诉吗？

`D0001` 返回时不带原因，响应中没有可据以行动的内容，所以请求中没有什么可以更正。请附上
`payoutRequestId` 和收款人信息向 Waffo 反馈；单个决定能否被重新审视是 Waffo 侧的判断，
不是一个请求参数。

***

有一个你无法归类的码，或者行为与本页不符的码？
请附上 `payoutRequestId`、`payoutOrderId`（如果有）以及准确的码和消息
[联系客服](mailto:support@waffo.com)。


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