はじめに
API を書く上で欠かせないのが HTTPステータスコード。
しかし、「200 と 500 くらいしか普段意識していない…」という人も多いはずです。
ステータスコードを正しく使えると、
・API の可読性が上がる
・バグ調査が圧倒的に早くなる
・フロントエンドと円滑にコミュニケーションが取れる
・REST API の品質が一気に上がる
というメリットがあります。
この記事では よく使うステータスコードを “実際のAPI例” とともに理解できる ように解説します。
ステータスコードは5つのカテゴリに分かれる
ステータスコードは頭文字でカテゴリ分けされます。
| ステータス | カテゴリ |
|---|---|
| 1xx | 情報 |
| 2xx | 成功 |
| 3xx | リダイレクト |
| 4xx | クライアントのエラー |
| 5xx | サーバのエラー |
特に API 開発で重要なのは 2xx・4xx・5xx の3つです。
API 開発で「必ず使う」ステータスコード一覧
以下の8つを理解しておけば基本的なAPIは大抵作れます。
| コード | 意味 | 用途 |
|---|---|---|
| 200 OK | 成功 | データ取得・更新成功 |
| 201 Created | 作成成功 | 新規作成 |
| 204 No Content | 成功（返すデータなし） | 削除成功 |
| 400 Bad Request | リクエストが不正 | バリデーションエラー |
| 401 Unauthorized | 認証エラー | ログインしていない |
| 403 Forbidden | 権限なし | アクセス禁止 |
| 404 Not Found | データが存在しない | 存在しないID |
| 500 Internal Server Error | サーバエラー | 想定外の例外 |
実例で理解する：Laravel でステータスコードを返す
ここからは、
「実際に API を書く時にどう使うのか？」
を Laravel のコード例で説明します。
200 OK — データ取得成功
return response()->json([
'id' => 1,
'name' => 'Taro'
], 200);
フロント側ではよく見る形：
if (response.status === 200) {
// データ取得成功
}
201 Created — 新規作成成功
POST の後に返すのが基本。
$user = User::create($request->all());
return response()->json($user, 201);
ポイント：
作成したリソースを返すのが一般的
204 No Content — 成功だが返すデータなし
DELETE でよく使う。
$user->delete();
return response()->noContent(); // 204
注意：
204 のときはボディを返さない のがルール。
400 Bad Request — リクエストが不正
バリデーションエラー時に使います。
$request->validate([
'email' => 'required|email',
]);
// エラー時 422 を返すが実質 400 系のエラー
Laravel は自動で 422 Unprocessable Entity を返します。
401 Unauthorized — 認証エラー
ログインしていない場合。
if (!auth()->check()) {
return response()->json(['message' => 'Unauthorized'], 401);
}
403 Forbidden — 権限不足
ログイン済みでも、権限が不足している場合。
if (!$user->isAdmin()) {
return response()->json(['message' => 'Forbidden'], 403);
}
401 と 403 の違い：
| 状態 | コード |
|---|---|
| ログインしてない | 401 |
| ログインしてるけど権限がない | 403 |
404 Not Found — データが見つからない
GET /users/99999
のように存在しないIDの場合。
$user = User::find($id);
if (!$user) {
return response()->json(['message' => 'Not Found'], 404);
}
500 Internal Server Error — 想定外のエラー
例外が起きたとき。
try {
// 何かの処理
} catch (\Exception $e) {
return response()->json(['message' => 'Server Error'], 500);
}
API 開発では 基本的に500は出さないのが理想
ログに記録して原因調査するのが良い習慣です。
REST API でのステータスコードの「正しい使い分け」
具体的にどう使うのか、1つの流れにしてみると…
| 操作 | 返すべきコード |
|---|---|
| 一覧取得 | 200 |
| 詳細取得 | 200 |
| 作成成功 | 201 |
| 更新成功 | 200 |
| 削除成功 | 204 |
| バリデーション失敗 | 422 |
| 認証エラー | 401 |
| 権限エラー | 403 |
| 対象が存在しない | 404 |
| サーバ内部エラー | 500 |
REST API では コードの使い分けは設計品質の象徴 です。
今日のまとめ
・ステータスコードは API の「返事の種類」
・2xx（成功）、4xx（クライアントエラー）、5xx（サーバエラー）が重要
・特に 200 / 201 / 204 / 400 / 401 / 403 / 404 / 500 を押さえておけばOK
・Laravelでの返し方とフロントでの扱い方を理解しておくと実装が楽になる
・ステータスコードが正しく使えると API の品質が一気に上がる
明日の Day4 は…
「HTTPヘッダー入門」
Content-Type、Accept、Authorization、CORS、Cookie など
実務で使うヘッダーを取り扱います！