Seleccionar página

18 códigos de estado HTTP clave para desarrolladores

Categoría (s): Código y Snippets CSS | Seguridad Web | Tutoriales y Guías

Depurar aplicaciones web y APIs REST puede convertirse en un verdadero rompecabezas si solo te limitas a celebrar un código 200 o lamentar un 404. Cuando trabajas con integraciones, proxies inversos, microservicios o configuraciones en servidores de producción, comprender el lenguaje exacto en el que responde un servidor web es la diferencia entre resolver un error en cinco minutos o perder horas buscando a ciegas.

Los códigos de estado HTTP son respuestas estandarizadas emitidas por el servidor para indicar el resultado de una solicitud enviada por el cliente (navegador, aplicación móvil o cliente HTTP). Se organizan en cinco clases principales según su primer dígito, ofreciendo información inmediata sobre el éxito, redirección o fallos en la comunicación.

A continuación, analizamos los 18 códigos de estado HTTP más importantes organizados por categoría que todo desarrollador debe dominar para optimizar el rendimiento backend, asegurar sus sistemas y acelerar la resolución de incidencias.

1. Respuestas satisfactorias (2xx)

Los códigos de la serie 2xx confirman que la solicitud del cliente fue recibida, comprendida y procesada con éxito por el servidor.

200 OK

Es la respuesta estándar para solicitudes exitosas. Significa que el servidor procesó el requerimiento y devolvió los datos esperados en el cuerpo de la respuesta.

  • Uso común: Respuestas exitosas a peticiones GET con datos o páginas HTML.

201 Created

Indica que la solicitud ha tenido éxito y, como resultado, se ha creado un nuevo recurso en el servidor.

  • Uso común: Peticiones POST o PUT exitosas, como la creación de un nuevo usuario o entrada de blog. Retorna habitualmente el encabezado Location con la URL del nuevo recurso.

202 Accepted

La solicitud ha sido aceptada para su procesamiento, pero este no ha concluido. Es una respuesta no vinculante, lo que significa que no hay garantía de que el procesamiento finalice con éxito.

  • Uso común: Tareas asíncronas, procesamiento de archivos pesados en segundo plano o colas de trabajo (job queues).

204 No Content

El servidor procesó con éxito la solicitud, pero no devuelve ningún contenido en el cuerpo de la respuesta.

  • Uso común: Peticiones DELETE exitosas o peticiones PUT donde el cliente no requiere recibir el recurso actualizado.

2. Redirecciones (3xx)

La serie 3xx indica que el cliente debe realizar acciones adicionales para completar la solicitud, generalmente dirigirse a una nueva ubicación.

301 Moved Permanently

Indica que el recurso solicitado ha sido movido de forma definitiva a un nuevo URI especificado en el encabezado Location. Los navegadores y buscadores redirigen automáticamente y actualizan sus marcadores e índices SEO.

  • Uso común: Migraciones de dominio, cambios en la estructura de URLs o migración masiva de HTTP a HTTPS.

302 Found

Señala que el recurso solicitado reside temporalmente bajo una dirección diferente. A diferencia del código 301, los motores de búsqueda no transfieren la autoridad de enlace (Link Juice) a la nueva URL de forma definitiva.

  • Uso común: Redirecciones temporales por mantenimiento, pruebas A/B o pasarelas de pago.

3. Errores del cliente (4xx)

Los códigos 4xx señalan que la solicitud enviada por el cliente contiene errores sintácticos, parámetros inválidos o falta de autorización.

400 Bad Request

El servidor no puede o no procesará la solicitud debido a un error percibido en el cliente (sintaxis de solicitud malformada, encuadre de mensaje no válido o enrutamiento engañoso).

  • Uso común: Envío de JSON con errores de formato o campos obligatorios faltantes en la petición.

401 Unauthorized

Indica que la petición no ha sido ejecutada porque carece de credenciales válidas de autenticación para el recurso solicitado.

  • Uso común: Intentos de acceso a APIs protegidas sin enviar un token de autenticación (JWT, Bearer token) o con credenciales expiradas.

403 Forbidden

El servidor entiende la solicitud del cliente, pero se niega rotundamente a autorizarla. A diferencia del 401, autenticarse no cambiará la respuesta; el cliente no posee los permisos necesarios.

  • Uso común: Intento de acceso a directorios protegidos del servidor o falta de roles de administrador.

404 Not Found

El código más famoso de la web. El servidor no puede encontrar el recurso solicitado. En la web, esto significa que la URL no se reconoce; en una API, también puede significar que el endpoint es válido pero el recurso específico no existe.

  • Uso común: URLs mal escritas, archivos eliminados o IDs inexistentes en bases de datos.

405 Method Not Allowed

El método HTTP utilizado en la petición (GET, POST, PUT, DELETE) es reconocido por el servidor, pero ha sido deshabilitado o no es soportado para el recurso específico.

  • Uso común: Enviar una petición POST a un endpoint que únicamente acepta GET.

408 Request Timeout

El servidor se agotó esperando la solicitud completa del cliente. Ocurre cuando el cliente tarda demasiado tiempo en enviar la petición completa al servidor.

  • Uso común: Conexiones lentas, latencia de red extrema o pérdida de paquetes durante el envío de payloads.

4. Errores del servidor (5xx)

Los códigos 5xx indican que la solicitud era válida, pero el servidor falló al intentar procesarla por problemas internos o de infraestructura.

500 Internal Server Error

Un error genérico que indica que el servidor se encontró con una condición inesperada que le impidió completar la solicitud.

  • Uso común: Excepciones no controladas en el código backend, fallos de sintaxis en Scripts PHP/Node.js o errores de conexión con bases de datos.

501 Not Implemented

El servidor no soporta la funcionalidad requerida para completar la solicitud. Es la respuesta adecuada cuando el servidor no reconoce el método de la petición.

  • Uso común: Uso de métodos HTTP no estándar o APIs en fase preliminar donde ciertos endpoints aún no han sido programados.

502 Bad Gateway

Ocurre cuando un servidor actuando como puerta de enlace (gateway) o proxy inverso recibe una respuesta no válida desde el servidor ascendente (upstream).

  • Uso común: Nginx o Apache intentando comunicarse con PHP-FPM o Node.js cuando el proceso backend se ha caído.

503 Service Unavailable

El servidor no está listo para manejar la solicitud. Las causas comunes son un servidor en mantenimiento o saturado por exceso de tráfico.

  • Uso común: Picos imprevistos de tráfico que superan la capacidad del servidor o ventanas programadas de mantenimiento.

504 Gateway Timeout

Indica que un servidor actuando como proxy o gateway no recibió una respuesta a tiempo por parte del servidor ascendente para poder completar la petición.

  • Uso común: Consultas SQL de larga duración, scripts backend bloqueados o tareas externas pesadas que exceden el tiempo límite de tiempo de espera (timeout) del proxy.

505 HTTP Version Not Supported

El versión del protocolo HTTP utilizada en la petición no es soportada por el servidor.

  • Uso común: Peticiones utilizando versiones obsoletas o formatos experimentales no implementados en el servidor web.

Conclusión

Dominar los códigos de estado HTTP no solo simplifica las tareas de depuración en entornos de desarrollo y producción, sino que mejora la arquitectura de tus APIs y optimiza la experiencia de usuario final. Asegúrate de retornar siempre el código de estado preciso según la situación; esto facilitará enormemente la integración con clientes frontend y herramientas de monitoreo.

¿Cuál es el código de estado HTTP que te ha causado más dolores de cabeza recientemente en tus proyectos? ¡Déjanos tu comentario y comparte tus experiencias de depuración!

Preguntas Frecuentes (FAQ)

¿Cuál es la diferencia real entre un código 401 y un 403?

La diferencia radica en la identidad y los permisos. El código 401 Unauthorized significa que el servidor no sabe quién eres (falta autenticación o es inválida). El código 403 Forbidden significa que el servidor sabe exactamente quién eres, pero tu usuario o rol no tiene permiso para acceder al recurso solicitado.

¿Cómo afectan las redirecciones 301 y 302 al SEO de un sitio web?

El código 301 Moved Permanently transfiere la autoridad de enlace (Link Juice) y el posicionamiento histórico de la antigua URL a la nueva dirección en los motores de búsqueda. En cambio, el código 302 Found le indica a Google que la redirección es temporal, conservando el índice y la autoridad en la URL original.

¿Qué diferencia existe entre un error 502 Bad Gateway y un 504 Gateway Timeout?

Ambos errores involucran a un proxy inverso (como Nginx o Cloudflare). El error 502 Bad Gateway ocurre cuando el proxy intenta conectarse al servidor backend y este responde con un mensaje corrupto o no válido. El error 504 Gateway Timeout ocurre cuando el backend tarda más tiempo del permitido en responder, provocando que la conexión caduque.

¿Por qué mi API retorna un código 200 cuando ocurre un error interno?

Esto sucede cuando los desarrolladores capturan las excepciones en su código y devuelven un mensaje de error dentro del cuerpo JSON pero no configuran adecuadamente el encabezado de respuesta del servidor. Esta es una mala práctica conocida como Anti-patrón 200 OK, ya que confunde a los clientes de la API y dificulta el monitoreo automático.

Referencias:

MDN Web Docs: Códigos de estado de respuesta HTTP — https://developer.mozilla.org/es/docs/Web/HTTP/Status

IETF RFC 9110: HTTP Semantics (Status Codes) — https://www.rfc-editor.org/rfc/rfc9110.html#name-status-codes

W3C HTTP/1.1 Status Code Definitions — https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Compartir:

Divi WordPress Theme
Anuncio - Alojamiento para WordPress de SiteGround - Potente, pero fácil de usar. Increíble velocidad, herramientas y soporte. Haz clic para más información.
Ir al contenido