エラーハンドリング

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 Internal Server Error	サーバーエラー。処理が完了したかどうかは不明なため、状態を確認してから再実行
502, 503, 504	サーバーまたはネットワークの一時的なエラー。リトライ可能

一時的なエラーやネットワークタイムアウトが発生した場合は、リトライ間隔を徐々に延ばしながら同じ冪等キーでリトライすることを推奨します。

500 が返却された場合、処理が完了したかどうかは不明です。冪等キーを指定したリクエストでは、同じキーでリトライしても同じ 500 が返却されます。オブジェクトの取得や Webhook で状態を確認し、処理が完了していなければ新しい冪等キーで再実行してください。