エラーハンドリング
API エラーに対するハンドリング方法、リトライ戦略について
PAY.JP API のエラーを適切に処理するための方法について説明します。エラーレスポンスの技術仕様については、エラーレスポンス仕様を参照してください。
エラーハンドリングについて
API レスポンスのステータスコードに応じて、適切なエラーハンドリングを実装することが重要です。
ステータスコード別の対応方針
| ステータス | 対応方針 |
|---|---|
| 400 Bad Request | リクエストパラメーターを確認し修正。自動リトライは不要 |
| 401 Unauthorized | API キーを確認 |
| 402 Payment Required | カード決済失敗。ユーザーに別の支払い方法を案内 |
| 404 Not Found | リソース ID を確認 |
| 409 Conflict | 冪等キーの競合。詳細は冪等リクエストを参照 |
| 422 Unprocessable Entity | errors 配列の内容を確認しパラメーターを修正 |
| 500, 503, 504 | サーバーエラー。リトライ可能 |
リトライ戦略
サーバーエラー（500, 503, 504）やネットワークタイムアウトが発生した場合は、待機時間を徐々に長くしながらリトライすることを推奨します。
リトライすべきエラー
- 500 Internal Server Error
- 503 Service Unavailable
- 504 Gateway Timeout
- ネットワークタイムアウト
リトライすべきでないエラー
- 400 Bad Request（パラメーターの問題）
- 401 Unauthorized（認証の問題）
- 402 Payment Required（決済失敗）
- 404 Not Found（リソースが存在しない）
- 422 Unprocessable Entity（バリデーション失敗）
参考リンク
- 冪等リクエスト - 二重決済を防止する方法
- エラーレスポンス仕様 - エラーコードの完全な一覧
- PAY.JP ステータスページ - サービス稼働状況の確認