Como você trata erros e levanta exceções HTTP?

Question

Accepted Answer

FastAPI trata erros **levantando exceções** que converte em respostas HTTP apropriadas. `HTTPException` cobre a maioria dos casos; manipuladores de exceções customizados permitem que você controle a formatação de erros globalmente.

## Levantando 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=...)` é a forma idiomática de retornar um erro — FastAPI produz uma resposta JSON `{"detail": "..."}` com o status fornecido. O `detail` pode ser qualquer valor serializável em JSON (string, dict, list).

## Erros de validação são automáticos (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.
```

## Manipuladores de exceções customizados (formatação 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
```

Manipuladores de exceções customizados permitem que você mapeie suas próprias exceções (de domínio) para respostas, centralizando a formatação de erros e mantendo o código do manipulador limpo.

## Sobrescrevendo manipuladores padrão

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

## Por que isso importa

O tratamento adequado de erros é essencial para construir APIs confiáveis e profissionais, e a abordagem do FastAPI é limpa e consistente.

A `HTTPException` idiomática facilita o retorno de respostas de erro corretas com códigos de status e mensagens apropriados — fundamental para qualquer endpoint que possa falhar (não encontrado, proibido, estado inválido).

Igualmente valioso é o fato de que **erros de validação são tratados automaticamente** (falhas no Pydantic produzem respostas estruturadas 422 sem código da sua parte), e que **manipuladores de exceções customizados** permitem que você mapeie suas próprias exceções de domínio para respostas e imponha um formato de erro consistente em toda a API — melhorando tanto a manutenibilidade (lógica de erro centralizada) quanto a experiência do cliente (formas de erro previsíveis).

Entender `HTTPException`, erros de validação automáticos e manipuladores customizados cobre o espectro prático do tratamento de erros, tornando-se conhecimento importante para construir APIs robustas.