エラーレスポンス形式
APIエラーは以下の形式で返されます。string
エラーの種類(
authentication_error, invalid_request_error, payment_error, api_error)string
エラーコード(下記参照)
string
エラーの説明文
string
リクエストID(サポートへの問い合わせ時に使用)
string
エラーの原因となったパラメータ名(バリデーションエラー時)
array
詳細なエラー情報(バリデーションエラー時)各要素には
path(エラーが発生したフィールドの位置)と message(人間可読な説明)が
必ず含まれます。これら以外のプロパティに依存しないでください。また message の文言は
予告なく変更される場合があるため、文言による分岐は行わないでください。処理の分岐には
トップレベルの code を使用してください。認証エラー
バリデーションエラー
決済エラー
トークンエラー
Webhook決済エラーコード
決済が失敗した場合、payment.failed Webhookには、すべての決済プロバイダーで統一された形式の詳細なエラー情報が含まれます。
エラー構造
エラーカテゴリ
統一エラーコード
バリデーションエラー(APIリクエスト失敗 — 400レスポンスに表示、Webhookは発火しない):
ハンドリング例
元の決済プロバイダーのエラー詳細(PSP固有コード)は、APIレスポンスやWebhookには含まれません。統一された
codeとcategoryフィールドを使用して、適切なアクションを判断してください。返金エラー
リソースエラー
冪等性エラー
システムエラー
エラーハンドリングのベストプラクティス
1
HTTPステータスコードを確認
4xx: クライアントエラー(リクエストの修正が必要)5xx: サーバーエラー(リトライ可能)
2
エラーコードで処理を分岐
error.codeを使用して、エラータイプに応じた処理を実装してください3
リトライ戦略
5xxエラーやidempotency_key_in_useの場合は、指数バックオフでリトライしてくださいサンプルコード
Node.js