レスポンスコード
Waffo API のレスポンス形式:
{
"code": "0",
"msg": "Success",
"data": { ... }
}
code が "0" は成功を示します
- 失敗時、
code はエラーコード文字列になります(例: "A0003"、"E0001")
- レスポンスのフィールド名は
msg です(message ではありません)
エラーコードの分類
| プレフィックス | カテゴリ | 説明 |
|---|
| 0 | 成功 | — |
| A | 加盟店側エラー | パラメータ不正、権限不足など |
| B | ユーザー側エラー | 残高不足、決済タイムアウトなど |
| C | システムエラー | チャネル側の拒否、システムエラーなど |
| D | リスクコントロール拒否 | リスクコントロールにより取引がブロックされた |
| E | 不明なエラー | 重要: 決済が成功している可能性があります |
エラーコードの完全な一覧は エラーコードリファレンス を参照してください。
E0001 ステータス不明の処理
これは最も重要な例外シナリオです。 ネットワークタイムアウト、接続中断、またはサーバーが E0001 を返した場合、決済のステータスは不明です。
基本原則
- 失敗と判断しない: ネットワークタイムアウトは決済失敗を意味しません
- 注文を自動クローズしない: チャネル側で決済がすでに完了している可能性があります
- 新しい注文を作成しない: 元の
paymentRequestId で照会してください
SDK のエラータイプ
| 言語 | ステータス不明エラー | クライアントエラー |
|---|
| Node.js | WaffoUnknownStatusError | WaffoError |
| Java | WaffoUnknownStatusException | WaffoException |
| Go | *core.WaffoUnknownStatusError | *core.WaffoError |
SDK のエラータイプは 2 種類のみです。WaffoUnknownStatusError/Exception は決済が成功している可能性を示し、WaffoError/Exception はクライアント側のエラー(設定、署名など)を示します。
SDK のエラーコード
| エラーコード | タイプ | 説明 |
|---|
| S0001 | UnknownStatus | ネットワークエラー(タイムアウト、接続失敗) |
| E0001 | UnknownStatus | サーバーが不明なステータスを返した |
| S0002 | Error | 公開鍵が無効 |
| S0003 | Error | 署名に失敗 |
| S0004 | Error | レスポンスの署名検証に失敗 |
| S0005 | Error | リクエストのシリアライズに失敗 |
| S0007 | Error | 秘密鍵が無効 |
処理フロー
ネットワークタイムアウト / E0001 / WaffoUnknownStatusError
│
▼
元の paymentRequestId で照会
│
├── PAY_SUCCESS を取得 → ローカルステータスを成功に更新
├── ORDER_CLOSE を取得 → ローカルステータスを失敗に更新
└── それでも不明 → Webhook 通知を待機
コード例
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);
}
}