> ## 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 では何を意味するか、安全に再試行できる 4 つのコード、リクエストの変更が必要なコード、A0003 がフィールド名を含む理由、B で始まるコードが実際には何を指しているのかを説明します。

Payout は独自のエラーコード群を返します。プレフィックスは決済のものと似ており、いくつかのコードは重複していますが、**意味は同じではありません**。Payout のレスポンスを処理する際は、[決済のエラーコード](/docs/ja/developer-docs/tools-and-references/developer-tools/error-codes)ではなくこの表を読んでください。各リクエストフィールドに何を入れるべきかは[Payout リクエストフィールドガイド](/docs/ja/support/payout-request-field-guide)を参照してください。

## プレフィックスは何を意味しますか？

| プレフィックス | 分類 | 扱い方 |
| - | - | - |
| `A` | 貴社またはリクエストに関すること | リクエストまたは設定を修正してください。変更せずに再試行しないでください |
| `B` | **受取人**に関すること | 受取人の情報を修正するか、受取人にアカウントを修正してもらってください |
| `C` | Waffo または送金経路 | 一部は再試行可能です。表を参照してください |
| `D` | リスク上の理由で拒否 | 再試行しないでください。Waffo に連絡してください |
| `E` | 結果不明 | **決して失敗として扱わないでください。** 最終ステータスになるまで照会を続けてください |

## Payout のコード一覧

### A — 加盟店とリクエスト

| コード | メッセージ | HTTP | 対処 |
| - | - | - | - |
| `A0001` | Invalid Api secret key | 401 | 署名に使用したキーを確認してください |
| `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/ja/support/payout-request-field-guide)にあります。

### C — Waffo と送金経路

| コード | メッセージ | 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 | `SUCCESS` または `FAILURE` が得られるまで `/api/v1/payout/inquiry` を呼び続けてください |

## そのまま再試行できるコードと、リクエストの変更が必要なコードはどれですか？

送信時に再試行可能と分類されているのは、ちょうど 4 つのコードです。

| 再試行可能 | コード |
| - | - |
| ✅ | `A0013` — 重複作成が処理中 |
| ✅ | `C0001` — システムエラー |
| ✅ | `C0005` — 送金チャネルのエラー |
| ✅ | `E0001` — 不明なステータス |

それ以外はすべて、変更しない限り Payout は成功しないことを意味します。この 4 つは**同じ** `payoutRequestId` で再試行してください。それが冪等性の目的であり、2 件目の 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` が返りました。1 件の Payout が大きすぎるのですか、それとも枠を使い切ったのですか？

Payout における `A0008` は、**1 件あたりの Payout 金額**がそのコリドーで許可された範囲の外にあること、つまり最小値未満か最大値超過であることを指します。両方の境界は貴社の Payout 契約に由来し、Portal の Service → Payout ページに資金供給通貨で **Minimum Amount** と **Maximum Amount** として表示されます。使用している国、通貨ペア、決済手段の行と金額を照合してください。

他の 2 つは別のコードであり、それが見分け方になります。

| コード | 意味 |
| - | - |
| `A0008` | この Payout の金額がコリドーの許可範囲の外にある |
| `A0005` | アカウントレベルの制限を超過した |
| `A0012` | 資金供給通貨の精算済み残高が、Payout 金額とその手数料をまかなえない |
| `B0002` | 貴社側ではなく受取人側の制限 |

残高不足は `A0008` ではなく `A0012` です。どの口座から引き落とされるかは[Payout ウォレットと残高のカバー](/docs/ja/support/payout-wallet-and-coverage-faq)を参照してください。

## `A0010`「Operation not allowed in merchant contract」は実際には何を意味しますか？

依頼した Payout が、貴社の有効な Payout の取り決めでカバーされていないということです。確認する価値のある順に、よくある原因は次のとおりです。

1. **その組み合わせの契約がない。** 国、通貨ペア、決済手段の種別、決済手段のすべてが Service → Payout の 1 行に一致している必要があります。
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` は冪等であるため、同一内容の再送は 2 件目の Payout を作るのではなく元の注文を返します。**安全でない**のは、タイムアウト後に同じ Payout を*新しい* `payoutRequestId` で送ることです。それが 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.