APIエラーコードの理解は、APIを利用する際に非常に重要です。
エラーコードはリクエストが成功しなかった理由を示し、問題の原因と解決策を見つける手助けをします。
以下に、一般的なAPIエラーコードをメモしておきます。
個別のAPIの仕様については、該当APIのドキュメントを参照してください。
エラーコード
情報レスポンス（100系）
100系のステータスコードは、クライアントとサーバー間の通信がまだ進行中であることを示します。
主にプロトコルレベルの通信で使用され、最終レスポンスが送信される前の一時的な応答として利用されます。
- 100 Continue
クライアントがリクエストを続行しても問題ないことを示します。
サーバーがリクエストヘッダーを受信し、リクエスト本文を送る準備ができていることを伝えます。 - 101 Switching Protocols
サーバーがクライアントのプロトコル切り替え要求を受け入れたことを示します。
例えば、HTTPからWebSocketプロトコルに切り替える場合に使用されます。
成功ステータス（200系）
- 200 OK
リクエストが正常に処理されたことを示します。サーバーから期待するレスポンスが返されます。
リダイレクト（300系）
300系のステータスコードは、リクエストされたリソースの場所が変更された場合や、他のURLへリダイレクトする必要がある場合に使用されます。
- 301 Moved Permanently
リクエストされたリソースが恒久的に別のURLに移動されたことを示します。リソースの新しい場所がレスポンスに含まれており、以降はそのURLを使用するよう指示します。 - 302 Found (Temporary Redirect)
リクエストされたリソースが一時的に別のURLに移動している場合に返されます。クライアントはリクエストを再送信できますが、将来的には元のURLにアクセスする可能性があります。 - 304 Not Modified
リソースが更新されておらず、キャッシュされたバージョンを使用できることを示します。キャッシュ制御を効率化し、ネットワーク負荷を軽減するために使用されます。
クライアントエラー（400系）
- 400 Bad Request
リクエストに誤りがあり、サーバーが処理できない場合に発生します。
例えば、必要なパラメータが欠落している、またはデータ形式が不適切な場合です。 - 401 Unauthorized
認証が不足しているか、無効な認証情報が提供された場合に発生します。APIキーやトークンの確認が必要です。 - 403 Forbidden
サーバーがリクエストを拒否している場合に発生します。認証は済んでいるが、リクエストしたリソースへのアクセス権がない場合などが考えられます。 - 404 Not Found
リクエストしたリソースが見つからない場合に返されます。エンドポイントURLが間違っている場合や、リソースが存在しない場合に発生します。 - 405 Method Not Allowed
エンドポイントがサポートしていないHTTPメソッド（例えば、POSTではなくGETを要求）を利用した場合に発生します。 - 429 Too Many Requests
短期間に過剰なリクエストが送信されたため、レート制限を超えたときに返されます。
しばらく待ってから再リクエストするか、リクエスト頻度を調整する必要があります。
サーバーエラー（500系）
- 500 Internal Server Error
サーバーで予期しないエラーが発生した場合に返されます。
API提供側に問題がある可能性が高いです。 - 502 Bad Gateway
サーバーが不正なレスポンスを受け取った場合に返されます。
ネットワークやプロキシ、API提供側のサーバーに問題がある可能性があります。 - 503 Service Unavailable
サーバーが一時的に利用不可である場合に返されます。サーバーが過負荷状態にあるか、メンテナンス中であることを示しています。 - 504 Gateway Timeout
リクエストがタイムアウトし、サーバーが一定の時間内に応答しなかった場合に発生します。
サーバーが処理に時間を要している場合やネットワーク遅延の可能性があります。
トラブルシューティング
APIのエラーコードを理解することで、トラブルシューティングがスムーズに進みますが、それに加えて、エラー発生時の原因特定や解決方法をいくつか準備しておくとさらに効率的です。
400 Bad Request
例えば、400 Bad Requestが返された場合、リクエストボディやパラメータ形式を見直し、送信内容がAPIの仕様に沿っているかを再確認することが重要です。
特に、データ型やフォーマットの不一致が原因になることが多いので、これらを細かくチェックすると良いでしょう。
401 Unauthorized／403 Forbidden
また、認証エラーが発生する401 Unauthorizedや403 Forbiddenのケースでは、トークンやAPIキーの有効期限、アクセス権限が適切かを確認します。
多くのAPIはトークンの更新手順やリフレッシュメカニズムを備えているため、これらを適切に実装することで、無駄なエラーを未然に防げます。
505系
500系エラーについては、API提供者側のサーバー問題である可能性が高いため、リトライ戦略を検討することがポイントです。
例えば、数分後に再リクエストするか、エラー発生時に一定間隔で数回リトライする方法が考えられます。
また、エラーの詳細メッセージをログに記録することで、サポートに問い合わせる際に役立てることができます。
さらに、特定のエラーコードが頻発する場合、その傾向をログデータから分析することで、原因究明や改善策の立案がしやすくなります。
例えば、レート制限が多発する場合、頻繁にアクセスしているエンドポイントにキャッシュを導入することが効果的です。
エラーコードを理解して適切な対応策を講じることにより、サービス全体の安定性と品質を向上させることが可能です。
