Código de Estado de Response¶

De la misma manera que puedes especificar un modelo de respuesta, también puedes declarar el código de estado HTTP usado para la respuesta con el parámetro status_code en cualquiera de las path operations:

@app.get()
@app.post()
@app.put()
@app.delete()
etc.

Python 3.10+


from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

Nota

Ten en cuenta que status_code es un parámetro del método "decorador" (get, post, etc). No de tu función de path operation, como todos los parámetros y el body.

El parámetro status_code recibe un número con el código de estado HTTP.

Nota

status_code también puede recibir alternativamente un IntEnum, como el http.HTTPStatus de Python.

Hará lo siguiente:

Devolver ese código de estado en la respuesta.
Documentarlo como tal en el esquema OpenAPI (y por lo tanto, en las interfaces de usuario):

Nota

Algunos códigos de respuesta (ver la siguiente sección) indican que la respuesta no tiene un body.

FastAPI sabe esto, y producirá documentación OpenAPI que indica que no hay cuerpo de respuesta.

Sobre los códigos de estado HTTP¶

Nota

Si ya sabes qué son los códigos de estado HTTP, salta a la siguiente sección.

En HTTP, envías un código de estado numérico de 3 dígitos como parte de la respuesta.

Estos códigos de estado tienen un nombre asociado para ayudar a reconocerlos, pero la parte importante es el número.

En resumen:

100 - 199 son para "Información". Rara vez los usas directamente. Las respuestas con estos códigos de estado no pueden tener un body.
200 - 299 are for "Successful" responses. These are the ones you would use the most.
- 200 es el código de estado por defecto, que significa que todo estuvo "OK".
- Otro ejemplo sería 201, "Created" (Creado). Se usa comúnmente después de crear un nuevo registro en la base de datos.
- Un caso especial es 204, "No Content" (Sin Contenido). Esta respuesta se usa cuando no hay contenido que devolver al cliente, y por lo tanto la respuesta no debe tener un body.
300 - 399 son para "Redirección". Las respuestas con estos códigos de estado pueden o no tener un body, excepto 304, "Not Modified" (No Modificado), que no debe tenerlo.
400 - 499 are for "Client error" responses. These are the second type you would probably use the most.
- Un ejemplo es 404, para una respuesta "Not Found" (No Encontrado).
- Para errores genéricos del cliente, puedes simplemente usar 400.
500 - 599 son para errores del servidor. Casi nunca los usas directamente. Cuando algo sale mal en alguna parte del código de tu aplicación o del servidor, devolverá automáticamente uno de estos códigos de estado.

Consejo

Para saber más sobre cada código de estado y para qué sirve cada uno, consulta la documentación de MDN sobre códigos de estado HTTP.

Atajo para recordar los nombres¶

Veamos el ejemplo anterior de nuevo:

Python 3.10+


from fastapi import FastAPI

app = FastAPI()


@app.post("/items/", status_code=201)
async def create_item(name: str):
    return {"name": name}

201 es el código de estado para "Created" (Creado).

Pero no tienes que memorizar qué significa cada uno de estos códigos.

Puedes usar las variables de conveniencia de fastapi.status.

Python 3.10+


from fastapi import FastAPI, status

app = FastAPI()


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(name: str):
    return {"name": name}

Son solo una conveniencia, contienen el mismo número, pero de esa manera puedes usar el autocompletado del editor para encontrarlos:

Detalles Técnicos

También podrías usar from starlette import status.

FastAPI proporciona el mismo starlette.status como fastapi.status solo como una comodidad para ti, el desarrollador. Pero viene directamente de Starlette.

Cambiar el valor por defecto¶

Más adelante, en la Guía de Usuario Avanzada, verás cómo devolver un código de estado diferente al que declaras aquí por defecto.