Códigos de estado de respuesta en FastAPI

El código de estado HTTP es parte de la respuesta y se utiliza para informar al cliente del resultado del procesamiento de la solicitud. FastAPI te permite declarar un código de estado predeterminado en el decorador de la operación de ruta, y también modificarlo dinámicamente dentro de la función.


Declarar el código de estado

Usarstatus_codeel parámetro en el decorador para declarar el código de estado de respuesta:

Ejemplo

from fastapi import FastAPI, status

app = FastAPI()


# Al crear un recurso, se usa el código de estado 201
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

status_codees un parámetro del método decorador (por ejemplo,@app.post()), no un parámetro de la función de operación de ruta. Puede ser un número (como201), o también se pueden usar lasfastapi.statusconstantes de (recomendado, con soporte de autocompletado en el editor).


Referencia rápida de códigos de estado HTTP

RangoCategoríaCódigos de estado comunesSignificado
1xxInformación--Raramente se usa directamente
2xxÉxito200 OKSolicitud exitosa (código de estado predeterminado)
201 CreatedRecurso creado exitosamente
204 No ContentÉxito pero sin contenido devuelto
3xxRedirección304 Not ModifiedRecurso no modificado (caché válida)
4xxError del cliente400 Bad RequestSolicitud con formato incorrecto
401 UnauthorizedNo autenticado
403 ForbiddenAutenticado pero sin permisos
404 Not FoundRecurso no encontrado
5xxError del servidor500 Internal Server ErrorError interno del servidor

Usar las constantes de status

fastapi.statusproporciona constantes para todos los códigos de estado HTTP, es más conveniente usarlas con el autocompletado del editor:

Ejemplo

from fastapi import FastAPI, status

app = FastAPI()


# POST - Crear recurso, devuelve 201
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}


# DELETE - Eliminar recurso, devuelve 204 (sin contenido)
@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: int):
    # La operación de eliminación normalmente no devuelve contenido
    pass


# GET - Obtener recurso, devuelve 200 (predeterminado)
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

204 No Contentsignifica éxito pero sin contenido devuelto, adecuado para operaciones de eliminación. Ten en cuenta que una respuesta 204 no puede incluir un cuerpo de respuesta.


Constantes de códigos de estado comunes

ConstanteValorEscenario de uso
status.HTTP_200_OK200Solicitud GET exitosa (predeterminado)
status.HTTP_201_CREATED201POST crear recurso exitosamente
status.HTTP_204_NO_CONTENT204DELETE exitoso, sin contenido devuelto
status.HTTP_400_BAD_REQUEST400Error en los parámetros de la solicitud
status.HTTP_401_UNAUTHORIZED401No autenticado o token inválido
status.HTTP_403_FORBIDDEN403Sin permiso de acceso
status.HTTP_404_NOT_FOUND404Recurso no encontrado
status.HTTP_409_CONFLICT409Conflicto de recursos (por ejemplo, creación duplicada)
status.HTTP_422_UNPROCESSABLE_ENTITY422Fallo de validación de datos
status.HTTP_500_INTERNAL_SERVER_ERROR500Error interno del servidor

Resumen

  • Usar el parámetro del decoradorstatus_codepara declarar el código de estado predeterminado
  • Se recomienda usarfastapi.statusconstantes, con soporte de autocompletado en el editor
  • POST crea recursos con 201, DELETE elimina recursos con 204, GET obtiene recursos con 200
  • 4xx indica errores del cliente, 5xx indica errores del servidor
Otras extensiones