Cum gestionați erorile și ridicați excepții HTTP?

Question

Accepted Answer

FastAPI gestionează erorile prin **ridicarea excepțiilor** pe care le convertește în răspunsuri HTTP corespunzătoare. `HTTPException` acoperă majoritatea cazurilor; handlerii de excepții personalizate vă permit să controlați formatarea erorilor la nivel global.

## Ridicarea 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=...)` este modul idiomativ de a returna o eroare — FastAPI produce un răspuns JSON `{"detail": "..."}` cu statusul dat. `detail`-ul poate fi orice valoare serializabilă în JSON (string, dict, list).

## Erorile de validare sunt automate (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.
```

## Handleri de excepții personalizate (formatare globală)

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

Handlerii de excepții personalizate vă permit să mapați propriile excepții (de domeniu) la răspunsuri, centralizând formatarea erorilor și menținând codul handlerului curat.

## Suprascrierea handlerilor impliciti

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

## De ce conteaza

Gestionarea corectă a erorilor este esențială pentru construirea de API-uri fiabile și profesionale, iar abordarea FastAPI este curată și consecventă.

`HTTPException` idiomativ face ușor să returnați răspunsuri de eroare corecte cu coduri de stare și mesaje adecvate — fundamental pentru orice endpoint care poate eșua (nu a fost găsit, interzis, stare rea).

La fel de valoroasă este faptul că **erorile de validare sunt gestionate automat** (eșecurile Pydantic produc răspunsuri structurate 422 fără cod de la voi), și că **handlerii de excepții personalizate** vă permit să mapați propriile excepții de domeniu la răspunsuri și să impuneți un format de eroare consistent pe întregul API — îmbunătățind atât mentenabilitatea (logica erorilor centralizată) cât și experiența clientului (forme de eroare previzibile).

Înțelegerea `HTTPException`, erorilor de validare automate și a handlerilor personalizați acoperă spectrul practic al gestionării erorilor, ceea ce o face cunoaștere importantă pentru construirea de API-uri robuste.