Códigos HTTP: guía práctica para desarrolladores

Hola devs

La semana pasada pasé tres horas persiguiendo lo que parecía un problema complejo de autenticación, y al final era un 422 que estaba interpretando mal. Esa noche me recordó que casi todos conocemos el famoso 404, pero muchos tropezamos con los códigos más sutiles que pueden ahorrarnos horas de depuración.

Este es un repaso práctico a los códigos de estado HTTP pensado para que se te queden de verdad. Nada de documentación seca, solo situaciones reales del día a día.

Por qué importan de verdad El mes pasado, nuestra API devolvía 200 OK en operaciones fallidas y el frontend estaba enloqueciendo porque su manejo de errores no se disparaba. La solución fue usar códigos correctos. No es solo cumplir un estándar, es reducir fricción y hacer la vida más fácil a todo el equipo.

2xx Todo va bien 200 OK es el comodín fiable para lecturas y operaciones exitosas, pero no todo es 200. 201 Created indica que algo nuevo se ha creado, ideal para POST de recursos porque el cliente distingue entre obtener datos existentes y crear algo nuevo. 204 No Content es perfecto cuando cumples la operación y no necesitas cuerpo de respuesta, por ejemplo en DELETE o actualizaciones sin payload de vuelta.

3xx Mira en otro sitio 301 Moved Permanently sirve para cambios definitivos de ruta o dominio y ayuda al SEO. 302 Found es para redirecciones temporales como páginas de mantenimiento. 304 Not Modified habilita caché eficiente cuando el recurso no ha cambiado desde la última petición y ahorra ancho de banda.

4xx Tú la liaste 400 Bad Request es genérico, pero siempre conviene incluir un cuerpo de error con detalles de validación útiles. 401 Unauthorized significa inicia sesión o presenta credenciales. 403 Forbidden es te reconozco pero no tienes permiso. 404 Not Found es el clásico; a veces conviene devolverlo en lugar de 403 para no filtrar la existencia de recursos privados. 409 Conflict encaja cuando hay duplicados o conflictos de estado en el servidor. 422 Unprocessable Entity brilla cuando la solicitud está bien formada pero es semánticamente inválida, por ejemplo un email con formato válido pero dominio inexistente o una edad negativa.

5xx Yo la lié 500 Internal Server Error es el algo se rompió en nuestro lado y debe estar bien monitorizado y registrado en producción. 502 Bad Gateway suele indicar fallos entre servicios o un backend que no respondió bien. 503 Service Unavailable es ideal para ventanas de mantenimiento y conviene acompañarlo de cabecera Retry-After. 504 Gateway Timeout es el apropiado cuando expira el tiempo de espera en una dependencia.

Historias reales de depuración Un día el checkout empezó a devolver 502 de forma aleatoria; resultó ser un timeout del servicio de pagos, y nuestro gateway devolvía 502 en lugar de 504. Ajustamos timeouts y devolvimos 504 para los casos de expiración real. En otra ocasión, un endpoint de creación de usuarios siempre devolvía 200 OK aunque el correo ya existía, y el frontend mostraba éxito en registros fallidos; lo corregimos con 409 Conflict. También aprendimos que los 302 en flujos OAuth pueden liar a apps móviles, mejor respuestas de API con tokens y flujos explícitos.

Buenas prácticas REST en la vida real Listar recursos debería devolver 200 con la lista. Crear recursos debería devolver 201 con el identificador y metadatos. Recuperar por id devuelve 200 o 404 si no existe. Actualizar devuelve 200 o 204 según si envías recurso actualizado o no, y 404 si no se encuentra. Borrar devuelve 204 si se elimina y 404 si no existe. Mantén la coherencia en toda tu API para que los clientes puedan anticipar el comportamiento.

Patrones de gestión de errores Diferencia claramente validaciones de negocio con 422, conflictos con 409, autenticación con 401 y autorización con 403. Incluye un cuerpo de error estandarizado con campos como error, detalles y posibles sugerencias. En frontend, maneja flujos por rangos de estado para mostrar mensajes adecuados y no bloquear la UX.

Herramientas que te salvan DevTools del navegador con la pestaña Network te muestra estados y tiempos; copiar como curl ayuda a reproducir. Postman o Insomnia permiten colecciones, ambientes y tests para verificar estados esperados. Con curl puedes seguir redirecciones, ver cabeceras y obtener solo el código para automatizar chequeos en pipelines.

Los raros que conviene conocer 418 I am a teapot nació como broma, pero algunos lo usan para detectar automatismos o throttling con humor. 451 Unavailable for Legal Reasons aparece cuando el contenido se bloquea por motivos legales.

Errores comunes Todo es 200 es una mala idea; si falla, usa el estado que toca. No ignores el cuerpo de error; un 400 sin explicación no ayuda. No mezcles autenticación con autorización; 401 para credenciales, 403 para permisos. Monitoriza patrones de estados; un pico de 5xx puede adelantarte a quejas de usuarios.

Pruebas de estados En tus tests de integración, valida que crear devuelve 201 y que los recursos incluyen su id. Comprueba que una validación de email incorrecto devuelve 422 con detalles. Simula duplicados para 409. Asegúrate de que 404 aparece cuando corresponde y que 401 y 403 se activan en los flujos correctos. En APIs distribuidas, prueba timeouts y verifica 504.

Códigos de estado en proyectos reales y Q2BSTUDIO En Q2BSTUDIO diseñamos y construimos APIs y plataformas robustas con foco en usabilidad y observabilidad. Somos una empresa de desarrollo de software con experiencia en aplicaciones a medida, software a medida, inteligencia artificial, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio, ia para empresas, agentes IA y power bi. Si quieres una API coherente, documentada y lista para escalar, echa un vistazo a nuestro enfoque de software a medida y aplicaciones a medida. Y si buscas llevar tu producto al siguiente nivel con modelos y agentes, descubre cómo aplicamos inteligencia artificial para empresas a casos reales, desde validación semántica hasta automatización de soporte con agentes IA.

Cierre Los códigos de estado no son números al azar, son un contrato de comunicación entre servidor y cliente. Elegir el adecuado mejora el debugging, la experiencia de usuario y la predictibilidad de tus APIs. La próxima vez que construyas un endpoint, pregúntate cuál es el estado más apropiado para este escenario. Tu yo del futuro, y tu equipo, te lo agradecerán. Y ya que estamos, cuál es el código que más te persigue en tus logs Yo diría que el 422 gana muchas batallas cuando se trata de validar negocio.

Recursos recomendados Revisa el registro oficial en IANA HTTP Status Codes, la guía completa en MDN y, para aprender con humor, HTTP Status Dogs.