Como você define códigos de status e cabeçalhos?

Question

Accepted Answer

FastAPI retorna `200 OK` por padrão, mas você controla o **código de status** (via decorator ou objeto response) e **cabeçalhos** quando você precisa de um comportamento diferente — importante para a semântica REST apropriada.

## Configurando um código de status padrão na rota

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 201 for resource creation
def create_item(item: Item):
    return item                                             # returns with 201

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)  # 204
def delete_item(id: int):
    ...
```

O parâmetro decorator `status_code` define o status de sucesso padrão. Usar as constantes `status` (por exemplo, `status.HTTP_201_CREATED`) é mais claro do que números mágicos. Códigos corretos importam: `201` para criado, `204` para sem conteúdo, etc.

## Códigos de status dinâmicos e cabeçalhos via objeto Response

```python
from fastapi import Response

@app.get("/items/{id}")
def get_item(id: int, response: Response):
    item = db.get(id)
    if not item:
        response.status_code = status.HTTP_404_NOT_FOUND   # set dynamically
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # set a custom header
    return item
```

Injetar um parâmetro `Response` permite que você defina o código de status e cabeçalhos **condicionalmente** em tempo de execução.

## Por que isso importa

```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",
                            headers={"X-Error": "NotFound"})   # status + detail + headers
    return item
```

Para respostas de erro, `raise HTTPException(...)` é a maneira idiomática — define o status, uma mensagem JSON `detail` e cabeçalhos opcionais.

## Retornando uma Response personalizada diretamente

```python
from fastapi.responses import JSONResponse
return JSONResponse(content={...}, status_code=202, headers={"X-Custom": "v"})
```

Códigos de status e cabeçalhos apropriados são essenciais para construir APIs REST corretas e bem-comportadas — clientes e ferramentas dependem da semântica HTTP padrão (201 para criado, 404 para não encontrado, 204 para sem conteúdo, etc.), portanto retornar o código correto faz parte de um contrato de API de qualidade.

FastAPI oferece controle limpo: um `status_code` padrão na rota para o caso comum, o objeto `Response` injetável para códigos/cabeçalhos dinâmicos e `HTTPException` como a maneira idiomática de sinalizar erros com o status apropriado e um detalhe JSON.

Compreender esses mecanismos — e usar as constantes `status` para clareza — é conhecimento cotidiano para construir APIs que se comportam corretamente e se comunicam claramente com seus consumidores.