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}

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}

204 No Content成功を表しますが返すコンテンツはなく、削除操作に適しています。204レスポンスにはレスポンスボディを含めることができないことに注意してください。


よく使うステータスコード定数

定数值使用シーン
status.HTTP_200_OK200GETリクエスト成功(デフォルト)
status.HTTP_201_CREATED201POSTリソース作成成功
status.HTTP_204_NO_CONTENT204DELETE成功、返すコンテンツなし
status.HTTP_400_BAD_REQUEST400リクエストパラメータエラー
status.HTTP_401_UNAUTHORIZED401未ログインまたはトークン無効
status.HTTP_403_FORBIDDEN403アクセス権限なし
status.HTTP_404_NOT_FOUND404リソースが存在しない
status.HTTP_409_CONFLICT409リソース競合(例:重複作成)
status.HTTP_422_UNPROCESSABLE_ENTITY422データ検証失敗
status.HTTP_500_INTERNAL_SERVER_ERROR500サーバー内部エラー

まとめ

  • デコレータのstatus_codeパラメータでデフォルトステータスコードを宣言
  • を使用することを推奨fastapi.status定数はエディタのオートコンプリート対応あり
  • POSTリソース作成は201、DELETEリソース削除は204、GETリソース取得は200
  • 4xxはクライアントエラー、5xxはサーバーエラーを示します
その他の拡張