レスポンスステータスコード¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

レスポンスモデルを指定するのと同じ方法で、レスポンスに使用されるHTTPステータスコードを以下のpath operationsのいずれかのstatus_codeパラメータで宣言することもできます。

@app.get()
@app.post()
@app.put()
@app.delete()
etc.

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

備考

status_codeは「デコレータ」メソッド（get、postなど）のパラメータであることに注意してください。すべてのパラメータやボディのように、path operation functionのものではありません。

status_codeパラメータはHTTPステータスコードを含む数値を受け取ります。

情報

status_codeは代わりに、Pythonのhttp.HTTPStatusのように、IntEnumを受け取ることもできます。

これは:

レスポンスでステータスコードを返します。
OpenAPIスキーマ（およびユーザーインターフェース）に以下のように文書化します:

備考

いくつかのレスポンスコード（次のセクションを参照）は、レスポンスにボディがないことを示しています。

FastAPIはこれを知っていて、レスポンスボディがないというOpenAPIドキュメントを生成します。

HTTPステータスコードについて¶

備考

すでにHTTPステータスコードが何であるかを知っている場合は、次のセクションにスキップしてください。

HTTPでは、レスポンスの一部として3桁の数字のステータスコードを送信します。

これらのステータスコードは、それらを認識するために関連付けられた名前を持っていますが、重要な部分は番号です。

つまり:

100 - 199 は「情報」のためのものです。直接使うことはほとんどありません。これらのステータスコードを持つレスポンスはボディを持つことができません。
200 - 299 は「成功」のレスポンスのためのものです。これらは最も利用するであろうものです。
- 200はデフォルトのステータスコードで、すべてが「OK」であったことを意味します。
- 別の例としては、201（Created）があります。これはデータベースに新しいレコードを作成した後によく使用されます。
- 特殊なケースとして、204（No Content）があります。このレスポンスはクライアントに返すコンテンツがない場合に使用されるため、レスポンスはボディを持ってはいけません。
300 - 399 は「リダイレクト」のためのものです。これらのステータスコードを持つレスポンスは304（Not Modified）を除き、ボディを持つことも持たないこともできます。304はボディを持ってはいけません。
400 - 499 は「クライアントエラー」のレスポンスのためのものです。これらは、おそらく最も多用するであろう2番目のタイプです。
- 例えば、404は「Not Found」レスポンスです。
- クライアントからの一般的なエラーについては、400を使用することができます。
500 - 599 はサーバーエラーのためのものです。これらを直接使うことはほとんどありません。アプリケーションコードやサーバーのどこかで何か問題が発生した場合、これらのステータスコードのいずれかが自動的に返されます。

豆知識

それぞれのステータスコードとどのコードが何のためのコードなのかについて詳細はMDN documentation about HTTP status codesを参照してください。

名前を覚えるための近道¶

先ほどの例をもう一度見てみましょう:

Python 3.9+

from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

201は「作成完了」のためのステータスコードです。

しかし、それぞれのコードの意味を暗記する必要はありません。

fastapi.statusの便利な変数を利用することができます。

Python 3.9+

from fastapi import FastAPI, status

app = FastAPI()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

それらは単なる便利なものであり、同じ番号を保持しています。しかし、その方法ではエディタの自動補完を使用してそれらを見つけることができます。

技術詳細

また、from starlette import statusを使うこともできます。

FastAPI は、開発者の利便性を考慮して、fastapi.statusと同じstarlette.statusを提供しています。しかし、これはStarletteから直接提供されています。

デフォルトの変更¶

後に、高度なユーザーガイドで、ここで宣言しているデフォルトとは異なるステータスコードを返す方法を見ていきます。