エラーの処理とHTTP例外の発生方法は？

Question

Accepted Answer

FastAPIは例外を**発生させる**ことでエラーを処理し、適切なHTTP応答に変換します。`HTTPException`はほとんどのケースをカバーしており、カスタム例外ハンドラーはエラー形式をグローバルに制御できます。

## なぜ重要なのか

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")   # → 404 JSON response
    if not item.is_public:
        raise HTTPException(status_code=403, detail="Forbidden")
    return item
```

`raise HTTPException(status_code=..., detail=...)`はエラーを返すための慣例的な方法です — FastAPIは指定されたステータスで`{"detail": "..."}`というJSON応答を生成します。`detail`はJSON化可能な任意の値（文字列、辞書、リスト）です。

## 検証エラーは自動的（422）

```text
When request data fails Pydantic validation, FastAPI AUTOMATICALLY returns a 422
with a structured list of exactly which fields are wrong — you write nothing.
```

## カスタム例外ハンドラー（グローバルな形式）

```python
from fastapi import Request
from fastapi.responses import JSONResponse

class ItemNotFound(Exception):
    def __init__(self, item_id: int): self.item_id = item_id

@app.exception_handler(ItemNotFound)         # handle a custom exception type globally
def handle_not_found(request: Request, exc: ItemNotFound):
    return JSONResponse(status_code=404, content={"error": f"Item {exc.item_id} not found"})

@app.get("/items/{id}")
def get(id: int):
    raise ItemNotFound(id)        # raise your domain exception; the handler formats it
```

カスタム例外ハンドラーを使うと、独自のドメイン例外をレスポンスにマッピングし、エラー形式を一元化し、ハンドラーコードをクリーンに保つことができます。

## デフォルトハンドラーをオーバーライドする

```python
from fastapi.exceptions import RequestValidationError

@app.exception_handler(RequestValidationError)   # customize the 422 validation-error format
def validation_handler(request, exc):
    return JSONResponse(status_code=422, content={"errors": exc.errors()})
```

## なぜ重要なのか

適切なエラー処理は、信頼性の高い専門的なAPIを構築するために不可欠であり、FastAPIのアプローチはクリーンで一貫しています。

慣例的な`HTTPException`により、適切なステータスコードとメッセージで正しいエラー応答を簡単に返すことができます — 失敗する可能性のあるエンドポイント（見つからない、禁止、不正な状態）のためには不可欠です。

同等に価値があるのは、**検証エラーが自動的に処理される**（Pydanticの失敗はあなたのコードなしで構造化された422応答を生成）ことであり、**カスタム例外ハンドラー**があなた独自のドメイン例外をレスポンスにマッピングし、API全体で一貫したエラー形式を強制できることです — 保守性（一元化されたエラーロジック）とクライアント体験（予測可能なエラー形式）の両方を向上させます。

`HTTPException`、自動検証エラー、およびカスタムハンドラーの理解は、エラー処理の実践的なスペクトラムをカバーし、堅牢なAPIを構築するための重要な知識になります。