Códigos de Estado HTTP: Qué Significan y Cuándo Usarlos
Más allá de 200 y 404. Una guía práctica de códigos de estado para desarrolladores de API.
Tu API devuelve 200. El cuerpo de respuesta dice {"error": "Not found"}.
Esto está mal. Los códigos de estado existen por una razón. Úsalos apropiadamente.
Las Cinco Categorías
1xx — Informacional. Raramente visto en la práctica.
2xx — Éxito. La solicitud funcionó.
3xx — Redirección. Ve a otro lugar.
4xx — Error del cliente. Hiciste algo mal.
5xx — Error del servidor. Nosotros hicimos algo mal.
Los Códigos que Realmente Usarás
Éxito (2xx)
200 OK — Éxito estándar. Usa para solicitudes GET que devuelven datos.
201 Created — El recurso fue creado. Usa después de un POST exitoso que crea algo.
204 No Content — Éxito, pero nada que devolver. Usa para DELETE o actualizaciones que no devuelven datos.
Errores del Cliente (4xx)
400 Bad Request — Solicitud malformada. JSON inválido, campos requeridos faltantes, tipos de datos incorrectos.
401 Unauthorized — Sin autenticación. El usuario necesita iniciar sesión.
403 Forbidden — Autenticado pero no permitido. El usuario existe pero carece de permiso.
404 Not Found — El recurso no existe. El clásico.
409 Conflict — La solicitud entra en conflicto con el estado actual. Nombre de usuario duplicado, discrepancia de versión.
422 Unprocessable Entity — Sintácticamente correcto pero semánticamente incorrecto. JSON válido pero reglas de negocio violadas.
429 Too Many Requests — Limitado por tasa. Desacelera.
Errores del Servidor (5xx)
500 Internal Server Error — Falla genérica del servidor. Algo se estrelló.
502 Bad Gateway — El servidor upstream falló. Tu servidor está bien, pero algo de lo que depende no.
503 Service Unavailable — Temporalmente caído. Mantenimiento o sobrecarga.
504 Gateway Timeout — El servidor upstream no respondió a tiempo.
Errores Comunes
200 con error en el cuerpo. Si es un error, usa un código de estado de error. No hagas que los clientes analicen el cuerpo para saber si tuvo éxito.
500 para errores de validación. ¿El usuario envió datos incorrectos? Eso es 400 o 422, no 500. El servidor no está roto, la solicitud sí.
Confusión entre 401 vs 403. 401 significa "¿quién eres?" 403 significa "sé quién eres, pero no".
404 para todo. "No encontrado" no siempre es la respuesta correcta. ¿Método incorrecto? 405. ¿Limitado por tasa? 429.
Diseñando APIs
Sé específico. Los clientes pueden manejar errores específicos inteligentemente. Los errores genéricos significan manejo genérico.
Incluye detalles del error en el cuerpo:
{
"error": "validation_failed",
"message": "El formato del email es inválido",
"field": "email"
}
El código de estado dice qué categoría de problema. El cuerpo explica específicamente.
Manejando Códigos de Estado como Cliente
2xx — Analiza la respuesta, procede normalmente.
4xx — Tu culpa. Registra, muestra al usuario, arregla la solicitud.
5xx — Culpa del servidor. Tal vez reintenta con retroceso. Tal vez alerta.
3xx — Sigue redirecciones automáticamente (la mayoría de clientes HTTP lo hacen).
No solo verifiques 200. Verifica éxito (2xx) y maneja otros casos apropiadamente.
Los códigos de estado son comunicación. Úsalos correctamente y las APIs se vuelven auto-documentadas. Úsalos mal y la depuración se vuelve adivinanza.