Códigos De Estado HTTP: Guía Completa Y Buenas Prácticas

Los códigos de estado HTTP son mensajes estandarizados que indican el resultado de una petición entre un cliente y un servidor.

Aunque puedan parecer simples números, conocer su funcionamiento es clave para el desarrollo web, la depuración de errores y el diseño de APIs que realmente funcionen. Esta guía desglosa los códigos más importantes, explica por qué no siempre basta con devolver un 200 OK y muestra las mejores prácticas que siguen los expertos.

Índice

• ¿Qué son los códigos de estado HTTP?
• Clases principales de códigos HTTP
• Códigos HTTP más comunes y su significado
• ¿Por qué no siempre usar 200 OK en una API?
• Buenas prácticas en APIs con códigos HTTP
• Diferencias entre errores comunes
• Tabla completa de códigos HTTP
• Preguntas frecuentes sobre códigos HTTP
• Conclusión y recomendaciones finales

¿Qué son los códigos de estado HTTP?

Los códigos de estado HTTP son respuestas que un servidor web devuelve al navegador o a una aplicación cliente tras recibir una solicitud. Estos códigos forman parte del protocolo Hypertext Transfer Protocol (HTTP) y se expresan en tres dígitos numéricos que indican si la operación fue exitosa, si hubo redirección, error del cliente o error del servidor.

La principal utilidad de estos códigos es permitir que tanto humanos como máquinas comprendan el resultado de una petición sin necesidad de interpretar el cuerpo de la respuesta. Por ejemplo, cuando se accede a una página inexistente, el servidor devuelve un 404 Not Found, mientras que un acceso correcto devuelve 200 OK.

Clases principales de códigos HTTP

Los códigos se organizan en cinco grandes grupos según la primera cifra:

1xx – Respuestas informativas

• 100 Continue: el servidor recibió los encabezados y el cliente puede continuar enviando el cuerpo.
• 101 Switching Protocols: el servidor acepta cambiar de protocolo.
• 103 Early Hints: adelanta metadatos útiles antes de la respuesta final.

2xx – Éxito

• 200 OK: petición procesada correctamente.
• 201 Created: recurso creado con éxito.
• 204 No Content: petición correcta, pero sin contenido en la respuesta.

3xx – Redirecciones

• 301 Moved Permanently: el recurso se ha trasladado a una nueva URL.
• 302 Found: redirección temporal.
• 307 Temporary Redirect: redirección temporal manteniendo el método HTTP.
• 308 Permanent Redirect: redirección permanente manteniendo el método HTTP.

4xx – Errores del cliente

• 400 Bad Request: la solicitud está mal formada.
• 401 Unauthorized: requiere autenticación.
• 403 Forbidden: el servidor entiende la petición pero la rechaza.
• 404 Not Found: recurso no encontrado.
• 408 Request Timeout: tiempo de espera agotado.

5xx – Errores del servidor

• 500 Internal Server Error: error genérico del servidor.
• 502 Bad Gateway: error en la comunicación entre servidores.
• 503 Service Unavailable: servidor sobrecargado o en mantenimiento.
• 504 Gateway Timeout: el servidor intermedio no recibe respuesta a tiempo.

Códigos HTTP más comunes y su significado

Aunque existen decenas de códigos, en el día a día los desarrolladores se encuentran con unos pocos de forma recurrente. Estos son los más relevantes:

• 200 OK: operación exitosa, el estado ideal en cualquier aplicación.
• 201 Created: confirma la creación de un recurso nuevo.
• 301 Moved Permanently: fundamental en SEO para redirigir tráfico de forma correcta.
• 400 Bad Request: aparece cuando el cliente envía parámetros inválidos.
• 401 Unauthorized: requiere autenticación, muy usado en APIs protegidas.
• 403 Forbidden: deniega acceso incluso si se proporcionan credenciales.
• 404 Not Found: probablemente el error más famoso en la web.
• 500 Internal Server Error: indica fallos inesperados en la aplicación.
• 502 Bad Gateway: un servidor intermedio recibió una respuesta inválida.
• 503 Service Unavailable: indica que el servidor no puede procesar la solicitud temporalmente.

¿Por qué no siempre usar 200 OK en una API?

Una mala práctica común en el diseño de APIs es devolver siempre un 200 OK aunque haya ocurrido un error. Esto obliga al cliente a leer el cuerpo de la respuesta para detectar el fallo, lo cual genera problemas:

• Los clientes no pueden diferenciar éxito de error sin lógica adicional.
• Las herramientas de monitorización no detectan fallos reales.
• Depurar en producción se convierte en un proceso caótico.

La alternativa es devolver el código apropiado. Por ejemplo, si un usuario solicita un recurso inexistente, se debe devolver un 404 Not Found. Si los datos no cumplen validación, corresponde un 400 Bad Request. Y si el servidor falla internamente, debe responder con 500 Internal Server Error.

Buenas prácticas en APIs con códigos HTTP

• 400 Bad Request → para parámetros inválidos o malformados.
• 404 Not Found → cuando el recurso solicitado no existe.
• 401 Unauthorized → si el cliente no proporciona credenciales.
• 403 Forbidden → si el cliente no tiene permisos aunque esté autenticado.
• 500 Internal Server Error → para errores inesperados del servidor.

El objetivo es coherencia: un cliente que interactúa con tu API debe predecir qué código recibirá en cada escenario. Esto facilita la integración, la automatización de pruebas y la experiencia del desarrollador.

Diferencias entre errores comunes

400 vs 404

400 Bad Request se usa cuando la petición está mal formada (ejemplo: un campo obligatorio vacío). En cambio, 404 Not Found se utiliza cuando la URL o el recurso solicitado no existe.

401 vs 403

401 Unauthorized implica que el cliente no está autenticado o las credenciales son inválidas. 403 Forbidden indica que la autenticación es válida, pero el usuario no tiene permisos para el recurso.

500 vs 502 vs 503

• 500 Internal Server Error: fallo genérico inesperado en la aplicación.
• 502 Bad Gateway: error de comunicación entre servidores intermedios.
• 503 Service Unavailable: el servidor está caído o saturado.

Tabla completa de códigos HTTP

Preguntas frecuentes sobre códigos HTTP

¿Qué es un error 418 “I’m a teapot”?

Se trata de un código definido en broma por el RFC 2324. No se usa en la práctica, pero se mantiene como parte de la cultura web.

¿Qué significa 504 Gateway Timeout?

Ocurre cuando un servidor intermedio, como un proxy, no recibe respuesta del servidor de destino a tiempo.

¿Cuál es el código de estado más usado en APIs REST?

El más habitual es 200 OK, acompañado de 201 Created para recursos nuevos y de 400, 404 y 500 para errores frecuentes.

Conclusión y recomendaciones finales

Los códigos de estado HTTP son mucho más que números: son el idioma que conecta a clientes y servidores. Usarlos correctamente hace que las aplicaciones sean más predecibles, que las APIs resulten más fáciles de integrar y que los sistemas sean más estables. Una API que devuelve siempre 200 OK oculta problemas y dificulta la vida de los desarrolladores, mientras que una API que devuelve el código adecuado transmite claridad y confianza.