エラーレスポンス仕様

PAY.JP API v2 のエラーレスポンスは RFC 9457 (Problem Details for HTTP APIs) に準拠しています。

このページではエラーレスポンスの技術仕様とエラーコードの一覧を提供します。エラーハンドリングの実践的な方法については、エラーハンドリングを参照してください。

レスポンス構造

エラーレスポンスは application/problem+json 形式で返却され、以下のような構造を持ちます。

基本構造

{
  "status": 400,
  "code": "invalid_status",
  "title": "Invalid Status",
  "detail": "This operation can only be executed when the payment_flow status is requires_payment_method. The current status is succeeded.",
  "instance": "/v2/payment_flows/pi_xxx",
  "type": "https://docs.pay.jp/v2/errors/invalid-status"
}

フィールド説明

• errors 配列の各要素
  • field: エラーが発生したフィールド名（ドット区切りでネストしたフィールド構造を表現）
  • message: エラーメッセージ

バリデーションエラー時の errors 配列

{
  "status": 422,
  "code": "validation_error",
  "title": "Validation Error",
  "detail": "The request parameters didn't pass validation.",
  "instance": "/v2/payment_flows",
  "type": "https://docs.pay.jp/v2/errors/validation-error",
  "errors": [
    {
      "field": "amount",
      "message": "Field required"
    },
    {
      "field": "currency",
      "message": "Input should be 'jpy'"
    }
  ]
}

HTTPステータスコード別エラー一覧

400 Bad Request

クライアントのリクエストに問題がある場合に返却されます。リソースのステータスが操作に適していない、必須パラメータが不足している、リクエストの形式が正しくないなどの理由で発生します。

401 Unauthorized

認証が必要または認証に失敗した場合に返却されます。APIキーが無効、または認証情報が不足している場合に発生します。

402 Payment Required

決済処理が失敗した場合に返却されます。カードが拒否された、カード処理中にエラーが発生した、3Dセキュア認証に失敗したなどの理由で発生します。

403 Forbidden

アクセス権限がない場合に返却されます。リソースへのアクセス権限が不足している場合に発生します。

404 Not Found

指定されたリソースが見つからない場合に返却されます。存在しないリソースIDを指定した場合などに発生します。

409 Conflict

冪等リクエスト機能で、リクエストが現在のリソース状態と競合している場合に返却されます。同じ冪等性キーが異なるパラメータで既に使用されている場合などに発生します。

422 Unprocessable Entity

リクエストパラメータのバリデーションに失敗した場合に返却されます。パラメータの型や形式が正しくない、必須フィールドが不足しているなどの理由で発生します。

500 Internal Server Error

サーバー内部でエラーが発生した場合に返却されます。

503 Service Unavailable

サーバーの一時的な障害やメンテナンス中などに発生します。