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
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
| Rango | Categoría | Códigos de estado comunes | Significado |
|---|---|---|---|
| 1xx | Información | -- | Raramente se usa directamente |
| 2xx | Éxito | 200 OK | Solicitud exitosa (código de estado predeterminado) |
201 Created | Recurso creado exitosamente | ||
204 No Content | Éxito pero sin contenido devuelto | ||
| 3xx | Redirección | 304 Not Modified | Recurso no modificado (caché válida) |
| 4xx | Error del cliente | 400 Bad Request | Solicitud con formato incorrecto |
401 Unauthorized | No autenticado | ||
403 Forbidden | Autenticado pero sin permisos | ||
404 Not Found | Recurso no encontrado | ||
| 5xx | Error del servidor | 500 Internal Server Error | Error 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
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
| Constante | Valor | Escenario de uso |
|---|---|---|
status.HTTP_200_OK | 200 | Solicitud GET exitosa (predeterminado) |
status.HTTP_201_CREATED | 201 | POST crear recurso exitosamente |
status.HTTP_204_NO_CONTENT | 204 | DELETE exitoso, sin contenido devuelto |
status.HTTP_400_BAD_REQUEST | 400 | Error en los parámetros de la solicitud |
status.HTTP_401_UNAUTHORIZED | 401 | No autenticado o token inválido |
status.HTTP_403_FORBIDDEN | 403 | Sin permiso de acceso |
status.HTTP_404_NOT_FOUND | 404 | Recurso no encontrado |
status.HTTP_409_CONFLICT | 409 | Conflicto de recursos (por ejemplo, creación duplicada) |
status.HTTP_422_UNPROCESSABLE_ENTITY | 422 | Fallo de validación de datos |
status.HTTP_500_INTERNAL_SERVER_ERROR | 500 | Error interno del servidor |
Resumen
- Usar el parámetro del decorador
status_codepara declarar el código de estado predeterminado - Se recomienda usar
fastapi.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