Códigos de Estado HTTP (200, 201, 400, 401, 404, 422, 500)
Domina el significado técnico de los códigos de respuesta HTTP en APIs REST, cuándo devolver cada uno y cómo inspeccionarlos en la barra de estado de Postman.
La Importancia de los Códigos de Estado en APIs REST
En una API REST profesional, el código de estado HTTP (Status Code) es lo primero que el cliente o aplicación móvil analiza para saber si la operación tuvo éxito o si ocurrió un error.
Muchos desarrolladores principiantes cometen el grave error de devolver siempre código
200 OK con un JSON como {"error": "Usuario no encontrado"}. Esto confunde a las librerías frontend (Axios, Fetch) y rompe la automatización de pruebas en Postman. ¡Usa siempre el código HTTP semántico correspondiente!
Los Códigos de Estado Indispensables en APIs
| Código | Nombre Oficial | Familia | Cuándo Devolverlo |
|---|---|---|---|
| 200 | OK | 2xx Éxito | Petición exitosa en GET, PUT o PATCH. Devuelve los datos solicitados. |
| 201 | Created | 2xx Éxito | Petición POST exitosa que creó un nuevo recurso en la base de datos. |
| 204 | No Content | 2xx Éxito | Operación exitosa pero sin cuerpo de respuesta (muy común al ejecutar un DELETE). |
| 400 | Bad Request | 4xx Error Cliente | Sintaxis JSON rota o cuerpo incomprensible por el servidor. |
| 401 | Unauthorized | 4xx Error Cliente | Falta el token de autenticación (JWT) o el token expiró. |
| 403 | Forbidden | 4xx Error Cliente | El usuario está autenticado pero no tiene permisos (ej. rol 'cliente' intentando entrar al panel de administración). |
| 404 | Not Found | 4xx Error Cliente | El endpoint no existe o el recurso con ese ID no fue encontrado en la base de datos. |
| 422 | Unprocessable Entity | 4xx Error Cliente | El JSON es sintácticamente válido pero falló la validación de negocio (ej. email ya registrado o clave menor a 8 caracteres). |
| 500 | Internal Server Error | 5xx Error Servidor | Excepción no controlada o error de código fatal en el backend. |
⚡ Respuesta Estándar de Error de Validación (422 Unprocessable Entity)
Estructura JSON profesional para informar errores específicos al cliente:
// HTTP/1.1 422 Unprocessable Entity
// Content-Type: application/json
{
"status": "error",
"codigo": 422,
"mensaje": "Los datos enviados no superaron las reglas de validación",
"errores": {
"email": [
"El correo electrónico ya se encuentra registrado en el sistema."
],
"password": [
"La contraseña debe contener al menos 8 caracteres y una letra mayúscula."
],
"edad": [
"Debes ser mayor de 18 años para abrir una cuenta."
]
}
}Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección¿Cuál es la diferencia técnica entre un código de estado 401 Unauthorized y un código 403 Forbidden en una API REST?
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.🚀 ¿Quieres dominar Manual de Postman: Pruebas de APIs REST & Automatización y crear proyectos reales?
Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.
🏛️ Autoría y Propiedad Intelectual: Obra educativa original de David Amador para Kilopolis Academia (Solucionáticos), estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.