レート制限とサーバーエラーへの対処

429レスポンスに対処する

レート制限されたリクエストは、detail.statusがrate_limit_exceededに設定された429 Too Many Requestsを返します。再試行する前にレスポンスヘッダーを確認してください。

• Retry-Afterは、拒否されたリクエストを再送するまで最低限待つ秒数を示します。
• X-RateLimit-Limitは、その時間枠の上限を示します。
• X-RateLimit-Remainingは、残りのリクエスト数を示します。
• X-RateLimit-Resetは、その時間枠がリセットされる時刻を示します。

Retry-Afterの時間だけ待ってから、指数バックオフとジッターを使って再試行してください。同時リクエスト数を減らし、時間枠のリセット直後に一斉送信するのではなく、処理をキューに入れます。

サーバーエラーに対処する

500レスポンスの公開本文には一般的なエラーとrequest_idが含まれ、内部例外の詳細は返されません。503は、必要なサービスが一時的に利用できないことを示す場合があります。

読み取り専用のリクエストは、上限を決めたバックオフで再試行してください。作成、更新、支払い、その他の状態変更リクエストを再試行する前に、最初の試行が完了したか確認します。タイムアウトや5xxレスポンスだけでは変更処理が失敗したとは判断できません。すぐに再送すると処理が重複するおそれがあります。

診断情報を残す

日時、メソッド、パス、ステータス、レスポンス本文、X-Request-Idを記録してください。x-api-keyの値は絶対にログに記録しないでください。自動再試行は少数回に制限し、それ以上失敗した場合は担当者の確認に回します。