FastAPI「422 Unprocessable Entity」の原因と直し方

要約

FastAPI の API を呼ぶと、処理に入る前に 422 Unprocessable Entity が返る。

{"detail":[{"type":"missing","loc":["query","q"],"msg":"Field required","input":null}]}

FastAPI は関数の引数に書いた型ヒントでリクエストの値を検証し、合わなければ RequestValidationError を出して 422 を返す（Handling Errors（新しいタブで開く）↗）。
関数の中の処理は実行されない。loc の 1 つ目が値の場所（path・query・body）、2 つ目が項目名で、msg が理由だ。
上の例は、必須のクエリパラメータ q を付けずに呼んだときの応答になる。
この記事の応答は Python 3.12・FastAPI 0.143.0・Pydantic 2.14.1 で実際に返ったものだ。

解決策

1. detail を読んで必須かどうかを決める

loc に出た項目を送るか、送らなくてもよい引数には既定値を付ける。

@app.get("/search")
def search(q: str | None = None, limit: int = 10):
    return {"q": q, "limit": limit}

この形なら /search は 200 で返る。limit=x のように型に合わない値は、既定値があっても 422 になる。

2. JSON として送る

await fetch("/items", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "pen", price: 100 }),
});

3. 包んで送るなら Body(embed=True)

クライアントが {"item": {...}} の形で送る仕様なら、受ける側を合わせる（Body - Multiple Parameters（新しいタブで開く）↗）。

from typing import Annotated
from fastapi import Body
 
@app.post("/items")
def create_item(item: Annotated[Item, Body(embed=True)]):
    return item

こうすると包んだ形は 200 になり、包まずに送った形のほうが ["body","item"] の missing になる。
どちらか一方にそろえる。

よくある原因

1. 必須の値が無い: 既定値の無いクエリパラメータは必須になる。q: str を付け忘れると上の missing になり、ボディのモデルの項目が欠けると loc が ["body","price"] になる。
2. 型に合わない値: item_id: int に abc を送ると int_parsing で「Input should be a valid integer」になる。"1.5" も整数にできないので同じエラーだが、"100" のような文字列は整数に変換されて通る。
3. JSON で送っていない: モデルで受けるボディは JSON として読まれる（Request Body（新しいタブで開く）↗）。
   フォーム形式で送ったり、JSON の文字列を Content-Type: text/plain で送ったりすると、loc が ["body"] の「Input should be a valid dictionary or object to extract fields from」になる。
   末尾のカンマなど JSON として壊れていると json_invalid になる。
4. ボディの包み方が違う: モデルが 1 つだけなら、FastAPI はその項目を JSON の最上位で受け取る。{"item": {...}} と包んで送ると、name と price の両方が missing になる。