Skip to main content

エラーレスポンス形式

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