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

# エラーハンドリング

> Waffo API のエラーコード分類と、ステータス不明例外の処理方法についてのガイド。

## レスポンスコード

Waffo API のレスポンス形式:

```json theme={null}
{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}
```

* `code` が `"0"` は成功を示します
* 失敗時、`code` はエラーコード文字列になります(例: `"A0003"`、`"E0001"`)
* レスポンスのフィールド名は `msg` です(`message` ではありません)

## エラーコードの分類

| プレフィックス | カテゴリ        | 説明                        |
| ------- | ----------- | ------------------------- |
| 0       | 成功          | —                         |
| A       | 加盟店側エラー     | パラメータ不正、権限不足など            |
| B       | ユーザー側エラー    | 残高不足、決済タイムアウトなど           |
| C       | システムエラー     | チャネル側の拒否、システムエラーなど        |
| D       | リスクコントロール拒否 | リスクコントロールにより取引がブロックされた    |
| E       | 不明なエラー      | **重要: 決済が成功している可能性があります** |

エラーコードの完全な一覧は [エラーコードリファレンス](/docs/en/developer-docs/tools-and-references/developer-tools/error-codes) を参照してください。

## E0001 ステータス不明の処理

<Warning>
  **これは最も重要な例外シナリオです。** ネットワークタイムアウト、接続中断、またはサーバーが `E0001` を返した場合、決済のステータスは不明です。
</Warning>

### 基本原則

* **失敗と判断しない**: ネットワークタイムアウトは決済失敗を意味しません
* **注文を自動クローズしない**: チャネル側で決済がすでに完了している可能性があります
* **新しい注文を作成しない**: 元の `paymentRequestId` で照会してください

### SDK のエラータイプ

| 言語      | ステータス不明エラー                      | クライアントエラー          |
| ------- | ------------------------------- | ------------------ |
| Node.js | `WaffoUnknownStatusError`       | `WaffoError`       |
| Java    | `WaffoUnknownStatusException`   | `WaffoException`   |
| Go      | `*core.WaffoUnknownStatusError` | `*core.WaffoError` |

<Note>
  SDK のエラータイプは 2 種類のみです。`WaffoUnknownStatusError`/`Exception` は決済が成功している可能性を示し、`WaffoError`/`Exception` はクライアント側のエラー(設定、署名など)を示します。
</Note>

### SDK のエラーコード

| エラーコード | タイプ           | 説明                     |
| ------ | ------------- | ---------------------- |
| S0001  | UnknownStatus | ネットワークエラー(タイムアウト、接続失敗) |
| E0001  | UnknownStatus | サーバーが不明なステータスを返した      |
| S0002  | Error         | 公開鍵が無効                 |
| S0003  | Error         | 署名に失敗                  |
| S0004  | Error         | レスポンスの署名検証に失敗          |
| S0005  | Error         | リクエストのシリアライズに失敗        |
| S0007  | Error         | 秘密鍵が無効                 |

### 処理フロー

```
ネットワークタイムアウト / E0001 / WaffoUnknownStatusError
    │
    ▼
元の paymentRequestId で照会
    │
    ├── PAY_SUCCESS を取得  → ローカルステータスを成功に更新
    ├── ORDER_CLOSE を取得  → ローカルステータスを失敗に更新
    └── それでも不明        → Webhook 通知を待機
```

### コード例

```typescript theme={null}
import { WaffoUnknownStatusError, WaffoError } from '@waffo/waffo-node';

try {
  const response = await waffo.order().create(params);
  if (response.isSuccess()) {
    // code === "0"、成功時の処理
  } else {
    // API がエラーコードを返した場合(例: A0003)、失敗として扱って問題ありません
  }
} catch (error) {
  if (error instanceof WaffoUnknownStatusError) {
    // 重要: 決済が成功している可能性があります。判定前に照会してください
    const inquiry = await waffo.order().inquiry({ paymentRequestId });
    if (inquiry.isSuccess()) {
      const status = inquiry.getData().orderStatus;
      await updateOrderStatus(paymentRequestId, status);
    }
    // 照会も失敗した場合は Webhook を待機
  } else if (error instanceof WaffoError) {
    // クライアントエラー(設定、署名)。修正後に再試行して問題ありません
    console.error('Client error:', error.errorCode, error.message);
  }
}
```