はじめに

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 など
実務で使うヘッダーを取り扱います！