API エラーに対するハンドリング方法についてまとめます。
エラーへの対処
成功ではないレスポンスを受け取った場合は、必要に応じて「PAY.JP のエラーコード」や「HTTP ステータスコード」をそれぞれ評価し、エラーハンドリングを行ってください。
多くの場合、エラーコードのみでも十分にハンドリングが可能ですが、後述のように想定外のエラーが返却される場合も考慮しておくと、より安全な運用が可能です。
また、返却されたエラー内容は可能な限り時刻、エラー内容、リクエスト内容等を保持しておくことで、お問い合わせの際にスムーズに問題が特定できるようになります。
ステータスコード
PAY.JP では、一般的な HTTP の規則にしたがって適切な HTTP ステータスコードを返却するよう努めております。
PAY.JP API では原則としてすべてのエラーレスポンスは JSON 形式で返却するようになっていますが、想定外のエラーによって JSON 形式ではないエラーレスポンスが返却される可能性も 0 ではないため、JSON 形式でなかった場合は HTTP ステータスを読み取るフォールバックも用意しておくのが望ましい方針となります。
402エラー
402 エラーは決済に関するエラー時に返却されるステータスコードです。
PAY.JP では、支払い作成・トークン作成などクレジットカード情報を使った決済操作が行われる API でこのステータスコードが返却される可能性があります。
本エラーの発生理由は多岐にわたり、また正確な理由はカード保有者や PAY.JP のような決済サービスプロバイダーからは問い合わせることができないため、カード保有者に対してカード会社へ問い合わせて原因を修正いただくよう、加盟店様からご案内いただく必要があります。
また、リトライなどで同一カードに対して本エラーを過剰に発生させた場合、カード会社より指摘や警告が入る場合があります。後述のリトライに関する項目もあわせてご確認ください。
エラーコード
エラーのより具体的な内容は、JSON エラーオブジェクトの code に記載されているエラーコードから判別できます。
リトライ
リクエストが何らかのエラーとなった場合、多くのシチュエーションでは短期的に同一のリクエストを行ってもエラーが解消されることはないばかりか、API 負荷や加盟店様がカード会社から指摘をうけるリスクになりうるため、単純なループ・try-catch 等によるリトライはお控えください。
402エラーのリトライ
402 エラーはカードの与信枠不足や不正利用懸念による取引中断、カード利用者自身によるロックなど、多岐にわたる理由により発生します。これらの理由は年々増加し続けています。カード保有者やカード会社によってその原因が取り除かれない限り、何度繰り返しても同じエラーが発生し続ける可能性が高いものとなっています。
一部例外として、日単位での利用上限設定のように1日程度待つと自然に解消するエラーも存在し得ることは確かですが、原則としてカード保有者による何らかのアクションが確認できない限り、402 エラーに対してリトライを行うべきではありません。
加えて、過剰に決済エラーが観測される場合、カード会社から利用状況の確認や是正の指摘が行われる場合があり、長期間改善されない場合は強制解約を含む措置が行われる可能性もあります。
どうしても自動的なリトライを行う場合は「カード保有者が自身でエラーを修正するための猶予時間（1日など）を空けて行う」「リトライも失敗した場合それ以上の試行を断念してカード保有者に連絡する」など、過度なリトライを行わないよう十分にご注意ください。
その他のエラーのリトライ
402 エラーについては決済特有のリスクが存在するため個別の項目を設けましたが、その他のエラーについては Web の一般原則通りの取り扱いとなります。冒頭に述べた通り、多くの場合において同一のリクエストを短期的に再送しても成功することはまれです。
- 400 系エラー
- リクエスト内容によるエラーのため、リクエスト内容を修正しない限りは解消されません。
- 500 系エラー
- 障害、不具合による 500 エラーや、メンテナンス時の 503 エラー等がありますが、いずれの場合も短期間に解消されることはまれなため、ステータスページでサービスの稼働状況をご確認いただく、お問い合わせフォームより不具合のご報告をいただく等の対応をお願いいたします。
リトライ可能なエラー
PAY.JP のレートリミットによって発生する 429 エラーは、例外的に一定の間隔を空けてリトライすることが想定されています。各種 SDK には自動的に 429 エラーに対してリトライを行う機能が搭載されているため、活用することで瞬間的なアクセス増にも柔軟に対処が可能です。