Wie behandelst du Fehler und wirfst HTTP-Ausnahmen?

Question

Accepted Answer

FastAPI behandelt Fehler durch das **Werfen von Ausnahmen**, die es in ordnungsgemäße HTTP-Antworten umwandelt. `HTTPException` deckt die meisten Fälle ab; benutzerdefinierte Exception-Handler ermöglichen dir, die Fehlerformatierung global zu steuern.

## HTTPException werfen

```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=...)` ist die idiomatische Methode, um einen Fehler zurückzugeben — FastAPI erzeugt eine JSON-Antwort `{"detail": "..."}` mit dem angegebenen Status. `detail` kann ein beliebiger JSON-serialisierbarer Wert sein (String, Dict, Liste).

## Validierungsfehler sind automatisch (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.
```

## Benutzerdefinierte Exception-Handler (globale Formatierung)

```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
```

Benutzerdefinierte Exception-Handler ermöglichen es dir, deine eigenen (Domänen-)Ausnahmen auf Antworten abzubilden, die Fehlerformatierung zu zentralisieren und den Handler-Code sauber zu halten.

## Standard-Handler überschreiben

```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()})
```

## Warum es wichtig ist

Ordnungsgemäße Fehlerbehandlung ist essentiell für den Aufbau zuverlässiger, professioneller APIs, und FastAPIs Ansatz ist sauber und konsistent.

Die idiomatische `HTTPException` macht es einfach, korrekte Fehlerantworten mit angemessenen Statuscodes und Meldungen zurückzugeben — grundlegend für jeden Endpunkt, der fehlschlagen kann (nicht gefunden, verboten, schlechter Zustand).

Gleich wertvoll ist, dass **Validierungsfehler automatisch behandelt werden** (Pydantic-Fehler erzeugen strukturierte 422-Antworten ohne Code von dir), und dass **benutzerdefinierte Exception-Handler** dir ermöglichen, deine eigenen Domänenausnahmen auf Antworten abzubilden und ein konsistentes Fehlerformat über die gesamte API durchzusetzen — verbessert sowohl Wartbarkeit (zentralisierte Fehlerlogik) als auch die Client-Erfahrung (vorhersehbare Fehlerformate).

Das Verständnis von `HTTPException`, automatischen Validierungsfehlern und benutzerdefinierten Handlern deckt das praktische Spektrum der Fehlerbehandlung ab, was es wichtiges Wissen für den Aufbau robuster APIs macht.