🔰
API実装で覚えておくべきHTTPステータスコード一覧
はじめに
実務でHTTPステータスコードを触れる機会が増えてきまして、一度体系的に知識をまとめる狙いで本記事を作成しました。
よく使用される代表的なステータスコードについてまとめています。
主にAPI設計や実装、これからAPIタスク行っていく方々に向けて、HTTPステータスコードの概要を把握してもえれば幸いです🙇♀️🙇♀️🙇♀️
2xx 成功レスポンス
| コード | 名称 | Rails | 使用場面 | 例 |
|---|---|---|---|---|
| 200 | OK | :ok |
リクエスト成功（GET, PUT, PATCH） | ユーザー情報取得、プロフィール更新 |
| 201 | Created | :created |
リソース作成成功（POST） | ユーザー登録、記事投稿 |
| 202 | Accepted | :accepted |
リクエスト受付、非同期処理 | バッチ処理開始、メール送信依頼 |
| 204 | No Content | :no_content |
成功したが返すデータなし（DELETE） | ユーザー削除、いいね取り消し |
3xx リダイレクト
| コード | 名称 | Rails | 使用場面 | 例 |
|---|---|---|---|---|
| 301 | Moved Permanently | :moved_permanently |
永続的なリダイレクト | URL変更、API版数変更 |
| 302 | Found | :found |
一時的なリダイレクト | ログイン画面への誘導 |
| 304 | Not Modified | :not_modified |
キャッシュ有効 | ETagベースのキャッシュ |
4xx クライアントエラー
認証・認可系
| コード | 名称 | Rails | 使用場面 | 例 |
|---|---|---|---|---|
| 401 | Unauthorized | :unauthorized |
認証が必要 | ログインしていない、トークン無効 |
| 403 | Forbidden | :forbidden |
権限不足 | 管理者権限が必要、他人のリソースへのアクセス |
リクエスト系
| コード | 名称 | Rails | 使用場面 | 例 |
|---|---|---|---|---|
| 400 | Bad Request | :bad_request |
リクエストが不正 | 必須パラメータ未指定、形式エラー |
| 404 | Not Found | :not_found |
リソースが存在しない | 存在しないユーザーID、削除済みデータ |
| 405 | Method Not Allowed | :method_not_allowed |
HTTPメソッドが許可されていない | GET専用エンドポイントにPOST |
| 406 | Not Acceptable | :not_acceptable |
Acceptヘッダーが不適切 | JSON APIにtext/html要求 |
| 409 | Conflict | :conflict |
リソースの競合 | 重複登録、同時更新エラー |
| 410 | Gone | :gone |
リソースが削除済み | 廃止されたAPI、削除されたコンテンツ |
| 412 | Precondition Failed | :precondition_failed |
事前条件エラー | If-Match失敗、楽観的ロック |
| 413 | Payload Too Large | :payload_too_large |
リクエストサイズ超過 | ファイルアップロード制限 |
| 415 | Unsupported Media Type | :unsupported_media_type |
Content-Type不正 | 画像APIにテキスト送信 |
| 422 | Unprocessable Entity | :unprocessable_entity |
バリデーションエラー | メールアドレス形式エラー、必須項目未入力 |
| 429 | Too Many Requests | :too_many_requests |
レート制限超過 | API呼び出し回数制限 |
5xx サーバーエラー
| コード | 名称 | Rails | 使用場面 | 例 |
|---|---|---|---|---|
| 500 | Internal Server Error | :internal_server_error |
サーバー内部エラー | 予期しない例外、プログラムバグ |
| 501 | Not Implemented | :not_implemented |
機能未実装 | 将来実装予定の機能 |
| 502 | Bad Gateway | :bad_gateway |
上流サーバーエラー | 外部API障害 |
| 503 | Service Unavailable | :service_unavailable |
サービス一時停止 | メンテナンス、高負荷 |
| 504 | Gateway Timeout | :gateway_timeout |
上流サーバータイムアウト | 外部API応答遅延 |
実装時の判断基準
400 vs 422 の使い分け
-
400: リクエスト形式が根本的に間違っている
- 必須パラメータが未指定
- JSONパース失敗
- 不正なHTTPメソッド
-
422: リクエスト形式は正しいが、内容にエラーがある
- バリデーションエラー
- ビジネスロジックエラー
- データベース制約エラー
401 vs 403 の使い分け
- 401: 認証が必要（ログインしていない）
- 403: 認証済みだが権限がない
404 vs 410 の使い分け
- 404: 一般的な「見つからない」
- 410: 意図的に削除されたリソース
API設計のベストプラクティス
エラーレスポンス統一
{
"error": {
"code": "VALIDATION_ERROR",
"message": "入力内容に誤りがあります",
"details": [
{
"field": "email",
"message": "メールアドレスの形式が正しくありません"
}
]
}
}
適切なステータスコード選択
- まず成功系を考える: 200, 201, 204
- 認証・認可をチェック: 401, 403
- リクエスト内容を検証: 400, 422
- リソースの存在確認: 404, 410
- サーバー側の問題: 500, 503
注意点
- 一貫性を保つ: 同じ種類のエラーには同じステータスコードを使用
- 適切な粒度: 細かすぎるステータスコードは避ける
- ドキュメント化: APIドキュメントに各ステータスコードの意味を記載
- 監視: 4xx/5xxエラーの発生頻度を監視
Rails での実装例
# 成功パターン
render json: data, status: :ok
render json: data, status: :created
head :no_content
# エラーパターン
render json: { error: "Unauthorized" }, status: :unauthorized
render json: { error: "Not found" }, status: :not_found
render json: { errors: @user.errors }, status: :unprocessable_entity
まとめ
ここまでお読みいただきありがとうございます！！
ステータスコードを理解することで、API実装などさまざまな面で役立ちます。
Discussion