成功の裏側を読み解く：HTTP 2xx ステータスコードの「正しい」使い分け術
ネットワークエンジニアとして現場に立っていると、トラブルシューティングの際、ついエラーコード（4xxや5xx）ばかりに目を奪われがちです。しかし、実は「成功」を表す2xx系コードの使い分けこそが、Web APIの品格を決め、クライアント側のエンジニアを助け、さらにはキャッシュ制御や負荷分散の効率を左右する、いわば「プロの矜持」とも言える部分なのです。
今日は、RFC 9110の定義をベースにしつつ、現場で「なぜそのコードを選ぶのか」という文脈を紐解いていきましょう。
—
1. 200 OK：万能選手にして、諸刃の剣
最も馴染み深い `200 OK` は、リクエストが成功し、レスポンスボディに結果が含まれていることを示します。
現場の視点:
一見万能ですが、何でもかんでも `200 OK` で返す設計は、クライアント側の処理を複雑にします。「中身は空だけど成功」なのか「中身はエラーだが通信は成功（ボディ内にエラーJSONがある）」なのかを判別させる必要があるからです。
- 活用例 (Python/requests):
import requests
典型的なGETリクエスト
response = requests.get(‘https://api.example.com/v1/resource/123’)
if response.status_code == 200:
# 成功してデータが返ってきた時
data = response.json()
print(f”取得完了: {data[‘name’]}”)
—
2. 201 Created：リソース誕生の証
POSTメソッドなどで新しいリソースが作成された際に返すべきコードです。この時、RFCの仕様上、`Location` ヘッダーで作成されたリソースのURIを返すのが礼儀です。
現場の視点:
クライアントは、`201` を受け取ったら次にそのリソースへアクセスする必要があるかもしれません。`Location` ヘッダーがあれば、フロントエンドやAPIクライアントは迷わず次のアクションへ繋げられます。
- curlによる確認:
-i オプションでレスポンスヘッダーを確認
curl -i -X POST https://api.example.com/v1/users \
-d ‘{“name”: “Engineer”, “email”: “dev@example.com”}’
サーバー側は Location: /v1/users/999 を返すのがベストプラクティス
—
3. 202 Accepted：非同期処理への招待状
これが意外と使われていない「渋い」コードです。クライアントのリクエストは受け付けたが、処理はまだ完了していない（バックグラウンドで走っている）ことを伝えます。
現場の視点:
重い計算や外部API連携など、レスポンスを待たせるとタイムアウトしてしまう処理に最適です。クライアントに「リクエストは届いたから安心して待っててくれ」と伝えることで、UXを損なわずに設計できます。
—
4. 204 No Content：余計なデータを送らない美学
「リクエストは成功したが、レスポンスボディに含めるデータはない」という場合に使います。
現場の視点:
例えば `DELETE` リクエストや、特定のステータス更新 `PUT` などです。クライアント側は「ボディをパースしようとしてエラーになる」という無駄な処理を回避できます。ネットワーク帯域の節約にもなる、極めて知的な選択です。
- Fetch APIでのハンドリング:
fetch(‘https://api.example.com/v1/resource/123’, { method: ‘DELETE’ })
.then(response => {
if (response.status === 204) {
// ボディがないことを前提に処理をスキップできる
console.log(‘リソースの削除完了’);
}
});
—
ステータスコード選びは「対話」である
Web APIはサーバーとクライアントの対話です。2xx系コードを適切に使い分けることは、単なる仕様遵守ではありません。
- 200 OK: 「これが結果だ」
- 201 Created: 「新しいやつを作ったぞ（場所はここだ）」
- 202 Accepted: 「受け取った、今裏で動かしてる」
- 204 No Content: 「成功した、でも返すものはない」
このように、コードひとつでサーバーの意図を明確に伝えることができます。デバッグの際、ログに並ぶステータスコードを見ただけで「設計者の意図」が手に取るようにわかる――そんな美しいAPIを設計できるエンジニアこそが、現場をリードできる存在だと私は信じています。
皆さんの次回のAPI設計で、この「意味のある選択」が役立つことを願っています。もし迷ったら、まずは「クライアントはこの後どう動くべきか？」を自問自答してみてください。それが正解への最短ルートです。
コメント