FastAPI レスポンスステータスコード
HTTPステータスコードはレスポンスの一部であり、クライアントにリクエストの処理結果を伝えるものです。FastAPIでは、パス操作デコレータでデフォルトのステータスコードを宣言したり、関数内で動的に変更したりすることができます。
ステータスコードの宣言
使用status_codeパラメータを使用してデコレータでレスポンスステータスコードを宣言します:
例
from fastapi import FastAPI, status
app = FastAPI()
# リソース作成時は201ステータスコードを使用
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
return {"name": name}
app = FastAPI()
# リソース作成時は201ステータスコードを使用
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
return {"name": name}
status_codeはデコレータメソッドのパラメータです(例:@app.post())、パス操作関数のパラメータではありません。数字(例:201)、またはfastapi.statusの定数を使用できます(推奨、エディタのオートコンプリート対応あり)。
HTTPステータスコード早見表
| 範囲 | カテゴリ | よく使うステータスコード | 意味 |
|---|---|---|---|
| 1xx | 情報 | -- | 直接使用されることはほとんどありません |
| 2xx | 成功 | 200 OK | リクエスト成功(デフォルトステータスコード) |
201 Created | リソース作成成功 | ||
204 No Content | 成功したが返すコンテンツなし | ||
| 3xx | リダイレクト | 304 Not Modified | リソース未変更(キャッシュ有効) |
| 4xx | クライアントエラー | 400 Bad Request | リクエスト形式エラー |
401 Unauthorized | 未認証 | ||
403 Forbidden | 認証済みだが権限なし | ||
404 Not Found | リソースが存在しない | ||
| 5xx | サーバーエラー | 500 Internal Server Error | サーバー内部エラー |
status 定数の使用
fastapi.statusすべてのHTTPステータスコードの定数が用意されており、エディタのオートコンプリートと併用するとより便利です:
例
from fastapi import FastAPI, status
app = FastAPI()
# POST - リソースを作成し、201を返す
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
return {"name": name}
# DELETE - リソースを削除し、204(コンテンツなし)を返す
@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
# 削除操作は通常コンテンツを返しません
pass
# GET - リソースを取得し、200(デフォルト)を返す
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
app = FastAPI()
# POST - リソースを作成し、201を返す
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
return {"name": name}
# DELETE - リソースを削除し、204(コンテンツなし)を返す
@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
# 削除操作は通常コンテンツを返しません
pass
# GET - リソースを取得し、200(デフォルト)を返す
@app.get("/items/{item_id}")
async def read_item(item_id: int):
return {"item_id": item_id}
204 No Content成功を表しますが返すコンテンツはなく、削除操作に適しています。204レスポンスにはレスポンスボディを含めることができないことに注意してください。
よく使うステータスコード定数
| 定数 | 值 | 使用シーン |
|---|---|---|
status.HTTP_200_OK | 200 | GETリクエスト成功(デフォルト) |
status.HTTP_201_CREATED | 201 | POSTリソース作成成功 |
status.HTTP_204_NO_CONTENT | 204 | DELETE成功、返すコンテンツなし |
status.HTTP_400_BAD_REQUEST | 400 | リクエストパラメータエラー |
status.HTTP_401_UNAUTHORIZED | 401 | 未ログインまたはトークン無効 |
status.HTTP_403_FORBIDDEN | 403 | アクセス権限なし |
status.HTTP_404_NOT_FOUND | 404 | リソースが存在しない |
status.HTTP_409_CONFLICT | 409 | リソース競合(例:重複作成) |
status.HTTP_422_UNPROCESSABLE_ENTITY | 422 | データ検証失敗 |
status.HTTP_500_INTERNAL_SERVER_ERROR | 500 | サーバー内部エラー |
まとめ
- デコレータの
status_codeパラメータでデフォルトステータスコードを宣言 - を使用することを推奨
fastapi.status定数はエディタのオートコンプリート対応あり - POSTリソース作成は201、DELETEリソース削除は204、GETリソース取得は200
- 4xxはクライアントエラー、5xxはサーバーエラーを示します