Web API開発で知るべきHTTPステータスコード(200/404/500)の意味

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "Widget",
  "price": 980
}

HTTP/1.1 201 Created
Location: https://api.example.com/orders/98765
Content-Type: application/json

{
  "id": 98765,
  "status": "created"
}

HTTP/1.1 204 No Content

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "validation_error",
  "message": "price must be >= 0",
  "fields": {
    "price": "must be non-negative"
  }
}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example", error="invalid_token"
Content-Type: application/json

{
  "error": "invalid_token",
  "message": "Access token is expired"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "forbidden",
  "message": "You do not have permission to access this resource"
}

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "not_found",
  "message": "Order 99999 was not found"
}

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1726300000
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Too many requests. Try again later."
}

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error": "internal_error",
  "message": "Unexpected server error"
}

HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{ "error": "bad_gateway" }

HTTP/1.1 503 Service Unavailable
Retry-After: 120
Content-Type: application/json

{ "error": "service_unavailable" }

HTTP/1.1 504 Gateway Timeout
Content-Type: application/json

{ "error": "gateway_timeout" }

# httpbinを使って代表的なステータスコードを取得する例
# 実行前に: pip install requests
import requests

def fetch_and_show(url: str) -> None:
    # URLへGETリクエストを送る
    resp = requests.get(url)
    # ステータスコードと理由句を表示
    print(f"URL={url}")
    print(f"status_code={resp.status_code}, ok={resp.ok}, reason={resp.reason}")
    # レスポンス本文の先頭だけを確認(長文対策)
    snippet = resp.text[:80].replace("\n", "\\n")
    print(f"body(80chars)={snippet}")
    print("-" * 40)

# 200, 404, 500 を順に確認
urls = [
    "https://httpbin.org/status/200",
    "https://httpbin.org/status/404",
    "https://httpbin.org/status/500",
]
for u in urls:
    fetch_and_show(u)

import requests
from requests import HTTPError

def get_json_or_raise(url: str):
    try:
        resp = requests.get(url)
        # ステータスコードが4xx/5xxならHTTPError例外を投げる
        resp.raise_for_status()
        # JSONとしてパース(本文がない204などは別途対処が必要)
        if resp.status_code == 204:
            return None
        return resp.json() if "application/json" in resp.headers.get("Content-Type", "") else resp.text
    except HTTPError as e:
        # 具体的なステータスで分岐
        status = e.response.status_code if e.response is not None else None
        if status == 401:
            print("認証エラー。トークンやAPIキーを確認してください。")
        elif status == 403:
            print("権限不足。ロールやスコープを確認してください。")
        elif status == 404:
            print("対象が見つかりません。IDやURLを確認してください。")
        elif status == 429:
            retry_after = e.response.headers.get("Retry-After", "unknown")
            print(f"レート制限。{retry_after}秒後に再試行してください。")
        elif status and 500 <= status < 600:
            print("サーバー側エラー。しばらく待ってから再試行を検討してください。")
        else:
            print(f"HTTPエラーが発生しました: {e}")
        return None

print(get_json_or_raise("https://httpbin.org/status/401"))
print(get_json_or_raise("https://httpbin.org/status/404"))
print(get_json_or_raise("https://httpbin.org/status/429"))
print(get_json_or_raise("https://httpbin.org/status/500"))

import requests

def handle_status(status: int, headers: dict) -> str:
    # 実践向け: ステータスに応じた人間向けメッセージを返す
    if 200 <= status < 300:
        return "成功。結果を処理します。"
    if status == 304:
        return "変更なし。キャッシュ利用を検討します。"
    if status == 400:
        return "入力不正。リクエストパラメータを見直してください。"
    if status == 401:
        return "未認証。APIキーやトークンを設定してください。"
    if status == 403:
        return "権限不足。アカウント権限やスコープを確認してください。"
    if status == 404:
        return "見つからない。ID/URLが正しいか確認してください。"
    if status == 409:
        return "競合。リソースの状態を再取得してからやり直してください。"
    if status == 412:
        return "前提条件失敗。ETagやIf-Matchの一致を確認してください。"
    if status == 429:
        ra = headers.get("Retry-After", "不明")
        return f"レート制限。{ra}秒後に再試行してください。"
    if 500 <= status < 600:
        return "サーバー側エラー。指数バックオフでリトライを検討します。"
    return f"想定外のステータス({status})。ログに残して調査してください。"

def demo(url: str):
    resp = requests.get(url)
    print(url, "->", resp.status_code, handle_status(resp.status_code, resp.headers))

demo("https://httpbin.org/status/200")
demo("https://httpbin.org/status/429")
demo("https://httpbin.org/status/503")

import requests
import time

def logged_get(url: str):
    start = time.time()
    resp = requests.get(url)
    elapsed_ms = int((time.time() - start) * 1000)
    # 実運用ではloggingモジュールを使用
    print(f"GET {url} -> {resp.status_code} ({elapsed_ms}ms)")
    return resp

logged_get("https://httpbin.org/status/200")
logged_get("https://httpbin.org/status/404")

# 簡易的な検証例。実プロジェクトではpytest/unittestを使用します。
import requests

def assert_status(url: str, expected: int):
    resp = requests.get(url)
    assert resp.status_code == expected, f"期待:{expected}, 実際:{resp.status_code}"

# 例: httpbinの既知のステータス
assert_status("https://httpbin.org/status/200", 200)
assert_status("https://httpbin.org/status/404", 404)
print("期待ステータスの検証に成功しました。")