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には含まれません。統一されたcodecategoryフィールドを使用して、適切なアクションを判断してください。

返金エラー

リソースエラー

冪等性エラー

システムエラー

エラーハンドリングのベストプラクティス

1

HTTPステータスコードを確認

  • 4xx: クライアントエラー(リクエストの修正が必要)
  • 5xx: サーバーエラー(リトライ可能)
2

エラーコードで処理を分岐

error.codeを使用して、エラータイプに応じた処理を実装してください
3

リトライ戦略

5xxエラーやidempotency_key_in_useの場合は、指数バックオフでリトライしてください

サンプルコード

Node.js