> ## 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.

# よくあるエラーのトラブルシューティング

> 加盟店が最も頻繁に遭遇する API エラーの診断と修正方法 — 無効な API キー（A0001）、署名の失敗（A0002）、パラメータ検証（A0003）、決済手段/契約の不一致（A0018）、不明ステータスのエラー（Exxxxx）、および再送が止まらない Webhook 通知について説明します。

失敗したすべての API 呼び出しは、レスポンスボディに `code` と `msg` を返します。コードの先頭の文字が、誰が対応すべきかを示します。

| プレフィックス | カテゴリ | 対応者 |
| - | - | - |
| `A`xxxxx | 加盟店関連のエラー | リクエストまたは設定を修正して再送 |
| `B`xxxxx | ユーザー関連のエラー | ユーザーを案内（残高、タイムアウト、承認） |
| `C`xxxxx | システム関連のエラー | Waffo 側の一時的な問題 — 後で再試行、またはサポートに連絡 |
| `D`xxxxx | リスク関連の拒否 | リスク管理によりブロック。想定外であればサポートに連絡 |
| `E`xxxxx | 不明なエラー | 最終的な Success/Failed ステータスになるまで照会を継続 |

完全な一覧は[エラーコードクイックリファレンス](/docs/ja/developer-docs/tools-and-references/developer-tools/error-codes)にあります。このページでは、最も多くのサポートチケットを生むコードを扱います。

## `A0001`「Invalid Api secret key」が返ります。API キーはどこで入手できますか？

`X-API-KEY` リクエストヘッダーが欠けているか、貴社アカウントに発行されたキーと一致していません。API キーは加盟店のオンボーディング時に Waffo から提供され、Merchant Portal のダッシュボードで確認できます。

よくある原因：

1. **環境の不一致** — サンドボックスと本番は**異なる API キーと RSA キー**を使用します。サンドボックスのキーを `https://api.waffo.com` に送る（または本番のキーを `https://api-sandbox.waffo.com` に送る）と `A0001` で失敗します。
2. リクエストに `X-API-KEY` ヘッダーがまったく含まれていない。

修正：対象環境のキーを Merchant Portal からコピーし、ベース URL がその環境と一致していることを確認してください。[サンドボックスとテスト](/docs/ja/developer-docs/getting-started/sandbox)を参照してください。

## `A0002`「Invalid signature」はどのようにデバッグすればよいですか？

Waffo は `X-SIGNATURE` ヘッダーを、**オンボーディング時に交換した加盟店の公開鍵**に対して **SHA256WithRSA** で検証します。検証に失敗するということは、貴社が生成した署名が Waffo が受信したボディと一致していないということです。次のチェックリストを順に確認してください。

1. **送信したとおりの生のリクエストボディ文字列**に署名してください。JSON としてパースして再度文字列化したり、整形済みや順序を並べ替えたコピーに署名したりしないでください。
2. この環境で **Waffo に登録済みの公開鍵に対応する秘密鍵**で署名していることを確認してください（サンドボックスと本番の RSA キーは別です）。
3. アルゴリズムが `SHA256WithRSA` であることを確認してください。
4. 新しい鍵ペアを生成した場合、切り替える前に新しい公開鍵を Waffo に登録する必要があります。

逆方向も重要です。Waffo はすべてのレスポンスと Webhook に自身の秘密鍵で署名し、貴社は Waffo の公開鍵（Merchant Portal → **Integration** メニュー）で検証します。**Waffo のレスポンスの検証に失敗した場合は、新しい取引の送信を止めて Waffo に連絡してください**。レスポンスを信頼できなくても、元のリクエストはすでに処理されている可能性があります。コード例：[Webhook 署名の検証](/docs/ja/developer-docs/webhook/signature-verification)。

## `A0003`「Parameter validation failed」は通常何が原因ですか？

`A0003` はリクエスト形式の拒否です。`msg` フィールドに詳細が含まれます。本番サポートで最も頻度の高い原因は次のとおりです。

1. **フィールド長の超過。** すべての文字列フィールドには宣言された最大長があります。`/api/v1/order/create` で加盟店が最も頻繁に超過するものは次のとおりです。

   | フィールド | 最大長 |
   | - | - |
   | `paymentRequestId` | String(32) |
   | `merchantOrderId` | String(64) |
   | `orderDescription` | String(128) |
   | `userEmail` | String(64) |
   | `userPhone` | String(16) |
   | `goodsName` | String(64) |
   | `goodsUrl` | String(128) |
   | `appName` | String(32) |
   | `notifyUrl` | String(256) |

2. **金額の形式。** 金額は小数点以下最大 2 桁の文字列です。そして **`JPY` のような小数なし通貨は整数でなければなりません**。実際の本番の例：`"orderCurrency":"JPY","orderAmount":"200.88"` は `A0003` で拒否され、`"201"` は受け付けられます。[通貨の取り扱い](/docs/ja/developer-docs/core-concepts/currency)を参照してください。

3. **形式の規約** — 時刻はミリ秒付きの ISO 8601（`2023-04-01T03:00:00.000Z`）、通貨は ISO 4217、国は ISO 3166-1 alpha-3（`IDN`、`PHL`）、`userPhone` は `+国番号-番号` の形式（例：`+62-08990013157`）です。

送信前にこれらをローカルで検証してください。フィールドごとの正確な契約は [Acquiring API 仕様](/docs/api-reference/introduction)にあります。

## `A0018` はどういう意味ですか？どう修正しますか？

Acquiring API では、`A0018` は **「Payment method in merchant order does not match with current merchant contract」** です。注文内の `payMethod`/国/プロダクトの組み合わせが、貴社が契約しているものではありません。

修正方法：

1. `/api/v1/paymethodconfig/inquiry` を呼び出します。レスポンスには、契約済みのすべての決済手段が、その `productName`（`ONE_TIME_PAYMENT` / `DIRECT_PAYMENT`）、`payMethodName`、`country`、`currentStatus`（`1` 利用可、`0` 利用不可）、および `fixedMaintenanceRules` の時間枠とともに列挙されます。
2. その一覧に `currentStatus` が `1` で現れる組み合わせのみを送信してください。どの決済手段を契約できるかは契約済みの設定によります。追加するには Merchant Portal を確認するか、連携サポートに連絡してください。
3. 隣接する 2 つのコードは似ていますが、契約の変更ではなくより精密な指定を求めています：`A0022`（`productName` を指定してください — 複数のプロダクトが見つかりました）と `A0033`（決済手段の国を指定してください — 複数の決済手段が見つかりました）。

注：同じコードは**サブスクリプション** API でも再利用されており、そこではそのユーザーが課金を続けるために利用できる決済手段がないこと（たとえば、利用可能な紐付け済みの決済手段が残っていない）を示します。エラーテキストは同じで、状況だけが異なるため、呼び出した API と合わせて読んでください。

## 契約に決済手段は含まれているのに、`userCurrency` を渡すとなぜ `A0018` が返るのですか？

`A0018` は**通貨ペアの次元**でも発生します。`orderCurrency` → `userCurrency` の組み合わせ（表示通貨ペア）は、決済手段自体とは独立して契約で有効化されている必要があります。たとえば、`orderCurrency=JPY` かつ `userCurrency=USD` の注文は、JPY→USD のペアが契約されていない限り `A0018` で拒否されます。カード決済が契約されていてもです。

2 つの解決策：

1. **`userCurrency` を省略する。** Waffo のチェックアウトが、現在の為替レートで注文金額をユーザーの現地通貨へ自動的に換算します。
2. **ペアを有効化する。** ユーザーに表示する通貨を自分で固定する必要がある場合は、Waffo の連携サポートに連絡して通貨ペアを契約に追加してください。

## 金額が原因で注文が拒否されました。限度額はどこで確認できますか？

各決済手段には通貨ごとに独自の最小・最大注文金額があり、一部の組み合わせには通常の通貨ルールに加えて精度のルールがあります（小数なし通貨は整数でなければならず、いくつかの決済手段は通貨が通常許容するより少ない小数桁しか受け付けません）。範囲または精度の外にある金額は、注文作成時に明示的なエラーで拒否されます。

限度額はプログラムから読み取れます。`/api/v1/paymethodconfig/inquiry` は、契約済みの各決済手段について `orderAmountMin` と `orderAmountMax` を、その `currency` とともに返します。レスポンスは決済手段ごとではなく契約ごとに 1 エントリであるため、同じ決済手段が異なる通貨と異なる限度額で複数回現れることがあります。課金する通貨で照合してください。Merchant Portal にも同じ設定が表示されます。

限度額は**契約に依存する固定値**です。決済手段を貴社アカウントで契約した時点で設定され、為替レートに応じて変動することはありません。クロスカレンシーの注文でも同様です。貴社に適用される値を確認するには、Merchant Portal の決済手段設定を確認するか、Waffo の連携担当者にお尋ねください。

## `E0001`「Unknown status」を受け取りました。決済は失敗ですか？

いいえ。不明は最終状態ではありません。`E`xxxxx のエラーは、Waffo 内または第三者システム内で結果がまだ確定していないことを意味します。取引を**保留中**として扱い、最終的な Success/Failed ステータスを受け取るまで照会（`/api/v1/order/inquiry`）を続けてください。`E` コードだけを根拠にユーザーに失敗を表示したり、再課金したりしないでください。

元のリクエストを再試行する際は、同じ `paymentRequestId` を再利用してください。これが冪等性キーです。**異なる**パラメータで再利用すると `A0011`「Idempotent param mismatch error」で失敗します。[冪等性](/docs/ja/developer-docs/core-concepts/idempotency)を参照してください。

## Waffo から同じ通知が繰り返し送られてきます。なぜですか？

貴社のエンドポイントが通知を確認応答していません。繰り返し発生するサポート事例：加盟店の Webhook エンドポイントが `Content-Type: application/octet-stream` と `{"message":"fail"}` で応答していたため、Waffo は通知を再配信し続けました。確認応答するには：

1. `Content-Type: application/json` で応答してください。
2. イベントを処理した後、ボディ `{"message":"success"}` で応答してください。`failed` / `unknown` の応答、200 以外のステータス、タイムアウト、パースできないボディはいずれも再試行スケジュールを発動させます。[Webhook の再試行](/docs/ja/developer-docs/webhook/retry)を参照してください。
3. ハンドラーを冪等にしてください。再試行があるということは、同じイベントが複数回届き得るということです。


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