¿Cómo estableces códigos de estado y encabezados?

Question

Accepted Answer

FastAPI devuelve `200 OK` de forma predeterminada, pero controlas el **código de estado** (a través del decorador u objeto de respuesta) y los **encabezados** cuando necesitas un comportamiento diferente — importante para la semántica REST correcta.

## Establecer un código de estado predeterminado en la ruta

```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):
    ...
```

El parámetro decorador `status_code` establece el estado de éxito predeterminado. Usar constantes `status` (p. ej., `status.HTTP_201_CREATED`) es más claro que números mágicos. Los códigos correctos importan: `201` para creado, `204` para sin contenido, etc.

## Códigos de estado y encabezados dinámicos a través del 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
```

Inyectar un parámetro `Response` te permite establecer el código de estado y los encabezados **condicionalmente** en tiempo de ejecución.

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

Para respuestas de error, `raise HTTPException(...)` es la forma idiomática — establece el estado, un mensaje JSON `detail` y encabezados opcionales.

## Devolver una Response personalizada directamente

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

## Por qué es importante

Los códigos de estado y encabezados correctos son esenciales para construir API REST correctas y bien comportadas — los clientes y herramientas dependen de la semántica HTTP estándar (`201` para creado, `404` para no encontrado, `204` para sin contenido, etc.), por lo que devolver el código correcto es parte de un contrato de API de calidad.

FastAPI te da control limpio: un `status_code` predeterminado en la ruta para el caso común, el objeto `Response` inyectable para códigos/encabezados dinámicos, e `HTTPException` como la forma idiomática de señalar errores con el estado apropiado y un detalle JSON.

Comprender estos mecanismos — y usar las constantes `status` para mayor claridad — es conocimiento cotidiano para construir API que se comportan correctamente y comunican claramente con sus consumidores.