¿Qué es el código de estado HTTP 201? Significado, ejemplos y cuándo usarlo
No todos los códigos de estado HTTP son iguales. Algunos simplemente confirman que una solicitud al servidor se realizó correctamente, mientras que otros tienen un significado especial. El código de estado 201 indica que el servidor ha creado correctamente un nuevo recurso. Usualmente, esto responde a una solicitud POST o, en ocasiones, a una solicitud PUT, que se utiliza con mayor frecuencia con servicios API.
En este artículo, explicaremos en detalle qué significa el código de respuesta 201 Created, analizaremos ejemplos de APIs REST y formularios de navegador, y lo compararemos con otros códigos de estado HTTP similares.
¿Qué es el código de estado HTTP 201?
El código de estado 201 significa que una solicitud se realizó correctamente y se creó un nuevo recurso.
Según la especificación HTTP/1.1, un código de respuesta 201 adecuado debe incluir un campo de encabezado de ubicación.
Este debe apuntar a la URI específica del recurso recién creado o principal. También puede incluir un cuerpo de respuesta con detalles sobre los datos solicitados.
Este comportamiento diferencia al código 201 de otros códigos de respuesta del servidor. Por ejemplo:
- 200 OK simplemente significa que la solicitud se realizó correctamente y devuelve los datos solicitados, pero no crea necesariamente una nueva entidad.
- 201 Created indica explícitamente que existe un nuevo recurso en la URI de la solicitud efectiva o en otra dirección de reenvío proporcionada en el encabezado de ubicación.
En la práctica, el código 201 se usa más a menudo en APIs REST donde una solicitud POST agrega un nuevo usuario, entrada de blog, archivo subido, o cualquier otro recurso objetivo. También puede aplicarse en formularios web, como una página de registro, donde un servidor completa la solicitud correctamente y se guarda una nueva entidad en la base de datos.
Cuándo usar 201 (y cuándo no)
El código de estado 201 se aplica cuando el servidor ha completado correctamente la solicitud de un cliente que genera un nuevo resultado. A continuación, se enumeran los casos de uso más comunes.
Casos de uso correctos
- Registro de usuario – Crear una nueva cuenta de usuario devuelve un 201 Created junto con un encabezado de ubicación que apunta a la página de perfil.
- Creación de entrada de blog – Publicar una entrada de blog con una solicitud POST debería devolver 201 una vez que el artículo esté guardado.
- Subida de archivo – Cuando un archivo subido se almacena en el servidor de origen, el código de respuesta debería ser 201 Created con un enlace al recurso objetivo.
- Pedido de ecommerce – Un proceso de pago donde el servidor prepara una nueva entrada de pedido puede devolver 201 más un cuerpo de respuesta con el ID del pedido.
Casos de uso incorrectos
El código 201 Created no debería usarse si no se ha generado un nuevo recurso. Errores comunes:
- Inicio de sesión o autenticación – Una solicitud se realizó correctamente, pero no agregó una nueva entidad. El código de estado adecuado suele ser 200 OK.
- Actualización de datos existentes – Una solicitud PUT que cambia una instancia actual debería devolver 200 OK o 204 No Content.
- Consultas de búsqueda – Devolver los datos solicitados no implica la creación de recursos; 200 OK es correcto.
- Intentos de creación duplicados – Si el servidor de origen se niega a crear porque la identidad del cliente ya existe, devuelve 409 Conflict.
Usar el código de respuesta incorrecto puede causar confusión para el agente de usuario y llevar a errores semánticos o respuestas no válidas en una API REST.
Ejemplo de API: Creación de un nuevo usuario
El código de estado 201 se ve con mayor frecuencia en las API cuando se devuelve un recurso recién creado tras la solicitud de un cliente. Veamos un caso común: crear un nuevo usuario en una API REST.
Por ejemplo, a continuación se muestra un ejemplo de solicitud POST realizada a api.example.com:
POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com"
}En esta solicitud POST, el agente de usuario solicita al servidor de origen que agregue una nueva entidad. A continuación, puedes ver una respuesta común del servidor:
HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json
{
"id": 123,
"name": "John Doe",
"email": "john@example.com"
}El código de respuesta del servidor 201 Created indica que la solicitud tuvo éxito y se agregó un nuevo recurso: un nuevo usuario, John Doe, su correo electrónico y un ID de usuario respectivo fueron creados exitosamente.
Puntos clave en este ejemplo:
- El campo de encabezado de ubicación proporciona la URI específica donde se puede acceder al recurso primario creado.
- El cuerpo de la respuesta devuelve los datos solicitados para el nuevo usuario, confirmando la creación del recurso.
- La solicitud se completó correctamente en un solo paso — no se requirió ningún método de solicitud ni dirección de reenvío adicionales.
Esta es la forma más correcta y conforme a los estándares de usar el código de respuesta HTTP 201 Created según la especificación HTTP.
Ejemplo de navegador: Demostración de formulario de registro (Escenario práctico)
Aunque el código de estado 201 es más común en las API, puedes verlo en acción con un formulario web sencillo.
Veamos una página de registro de demostración donde un visitante puede crear una nueva cuenta de usuario.
Al enviar el formulario, el servidor de origen procesa la solicitud del cliente, almacena los datos y devuelve la respuesta 201 Created.
En nuestra demostración:
- El visitante completa su nombre, correo electrónico y contraseña.
- El servidor valida los campos del encabezado de la solicitud y guarda los datos como un recurso recién creado en la base de datos.
- El código de respuesta del servidor es 201 Created, junto con un encabezado de ubicación que apunta al nuevo perfil.
- Una página de confirmación muestra los detalles del recurso solicitado, demostrando que la solicitud se cumplió correctamente.
Ten en cuenta que es poco probable ver códigos de respuesta 201 en el front-end de sitios web.
Esta demostración pretende ilustrar el proceso que suele ocurrir entre bastidores cuando el servidor procesa las solicitudes.
También puedes usar las herramientas de desarrollo y red del navegador para ver cómo se usa el código de estado en la práctica en aplicaciones reales.
201 vs. Otros códigos de estado similares
El código de respuesta HTTP 201 Created a menudo se confunde con otros códigos de éxito. A continuación, se muestra una comparación con respuestas relacionadas:
201 vs 200 OK
- 200 OK significa que la solicitud se realizó correctamente y se devuelven los datos solicitados.
- No indica que exista un recurso recién creado.
- Por ejemplo: obtener una entrada de blog o actualizar una instancia actual.
201 vs 202 Accepted
- 202 Accepted significa que la solicitud del cliente fue recibida y puede ser procesada más tarde.
- No hay garantía de que se cree una nueva entidad todavía.
- Por ejemplo: enviar un trabajo a una cola para su procesamiento de riesgos, como generar un PDF o gestionar un sistema de pago digital.
201 vs 204 No Content
- 204 No Content significa que la solicitud se realizó correctamente y no hay un cuerpo de mensaje que devolver.
- A menudo se usa para una solicitud PUT que actualiza un recurso existente.
- No se incluye ningún encabezado de ubicación ni nuevo recurso.
| Código de Respuesta | Significado | Cuándo usar | Escenario de ejemplo |
| 200 OK | Solicitud exitosa, devuelve recurso solicitado | Recuperación o actualización estándar | Obtener una entrada de blog |
| 201 Created | Solicitud resultó en un recurso recién creado | Creación de recursos vía POST/PUT | Crear un nuevo usuario |
| 202 Accepted | Solicitud aceptada para procesamiento, no completada aún | Tareas asíncronas, colas de trabajos | Generar un informe en segundo plano |
| 204 No Content | Solicitud exitosa, no se devuelve cuerpo de respuesta | Actualizaciones sin datos de retorno | Actualizar un perfil con PUT |
Conclusiones clave sobre el código de estado 201
Resumamos los puntos principales sobre el código 201:
- El código de estado HTTP 201 confirma que el servidor completó correctamente la solicitud de un cliente mediante la creación de un nuevo recurso.
- Un código de respuesta 201 adecuado del servidor debería incluir un campo de encabezado de ubicación que apunte a la URI específica del recurso recién creado y también puede devolver un cuerpo de respuesta con detalles sobre los datos solicitados.
- El código de respuesta 201 Created es más común en APIs REST para la creación de recursos (nuevo usuario, entrada de blog, archivo subido o pedido).
- No confundas 201 con otros códigos de estado HTTP como 200 OK, 202 Accepted o 204 No Content — cada uno comunica un resultado diferente del método de solicitud.
- Usar el código de estado HTTP correcto significa que el agente de usuario puede gestionar el recurso solicitado adecuadamente.
En resumen: 201 le indica al cliente, ‘La solicitud funcionó, y ahora existe un nuevo recurso’.
