Errores de cliente HTTP 4xx: significado, diagnóstico y soluciones

Qué significa este error y cómo reconocerlo

Un navegador, cliente de API o solicitud automatizada recibe un estado HTTP del 400 al 499. La respuesta puede contener una página de error breve, un objeto de error JSON, cabeceras explicativas o ningún cuerpo útil.

Entre las respuestas visibles habituales se incluyen:

• 400 Bad Request: El servidor no puede procesar la solicitud tal como la recibió.
• 401 Unauthorized: Falta la autenticación, no es válida o es necesaria para el recurso.
• 403 Forbidden: La solicitud se entiende, pero el acceso no está permitido.
• 404 Not Found: No se encuentra el recurso o la ruta solicitada.
• 405 Method Not Allowed: El recurso no admite el método HTTP utilizado.
• 409 Conflict: La solicitud entra en conflicto con el estado actual del recurso.
• 410 Gone: El recurso ya no está disponible de forma intencionada.
• 413 Content Too Large: El cuerpo de la solicitud supera un límite configurado o documentado.
• 429 Too Many Requests: El cliente ha superado un límite de frecuencia o cuota.

El mismo estado puede verse diferente según si lo generó la aplicación, un reverse proxy, una CDN o un firewall de aplicaciones web.

Causas principales, ordenadas por probabilidad

Causas habituales, en orden de diagnóstico

1. Solicitud con formato incorrecto o no válida — 400: Una sintaxis no válida, una URL codificada incorrectamente, un JSON no válido, un tipo de contenido incorrecto o la ausencia de datos obligatorios pueden impedir el procesamiento.
2. Autenticación ausente o no válida — 401: Es posible que la solicitud no incluya credenciales, contenga una credencial caducada o use credenciales que el endpoint no acepta.
3. Permisos insuficientes o una política de seguridad — 403: La identidad puede estar autenticada pero no autorizada, o una regla de IP, CDN, WAF, proxy o una política de la aplicación puede denegar el acceso.
4. Ruta o estado del recurso incorrectos — 404 o 410: La URL puede ser incorrecta, un despliegue puede no contener la ruta, un recurso puede haberse movido o su propietario puede haberlo eliminado deliberadamente.
5. Método HTTP no compatible — 405: El cliente utilizó GET, POST, PUT, PATCH o DELETE cuando el contrato del endpoint permite otro método.
6. Conflicto de estado o versión — 409: El cambio solicitado puede entrar en conflicto con el estado actual del recurso, con un objeto existente o con otra actualización.
7. La solicitud supera un límite — 413: El cuerpo, la carga o la solicitud codificada es mayor que el límite impuesto por la aplicación o un intermediario.
8. Demasiadas solicitudes — 429: El cliente ha superado un límite de frecuencia, concurrencia o cuota.

Una CDN, un WAF o un reverse proxy puede producir una respuesta 4xx antes de que la solicitud llegue al origen. En ese caso, el supuesto error de la aplicación puede pertenecer a una capa de red anterior.

Cómo solucionarlo

1. Captura la respuesta exacta

Registra el estado numérico, la URL completa, el método HTTP, la marca de tiempo, el tipo de solicitud y las cabeceras de respuesta relevantes. Para las solicitudes de API, registra también el tipo de contenido saneado, el tamaño de la solicitud y cualquier ID de correlación o de solicitud. No registres ni compartas contraseñas, claves de API, cookies ni tokens de acceso.

Compara la respuesta con una solicitud conocida como válida cuando exista. Comprueba si el cuerpo y las cabeceras de la respuesta identifican la aplicación de origen, el proxy, la CDN o el WAF.

2. Comprueba el contrato de la solicitud

Para 400, valida la codificación de la URL, los parámetros obligatorios, la sintaxis JSON o de formulario, el tipo de contenido y los campos requeridos. Confirma que el cliente envía el formato documentado por el endpoint en lugar de cambiar la configuración del servidor.

Para 405, verifica los métodos permitidos por el endpoint y asegúrate de que el cliente no esté siguiendo una redirección ni utilizando una URL orientada al navegador para una operación de API. Comprueba la cabecera de respuesta Allow cuando se proporcione.

Para 409, inspecciona el estado actual del recurso. Es posible que el objeto ya exista, haya cambiado desde que se leyó o no esté disponible para la transición solicitada. Sigue el comportamiento de conflictos o versionado de la aplicación en lugar de repetir ciegamente la escritura.

3. Comprueba la identidad y el acceso

Para 401, verifica que la autenticación esté presente, vigente y se envíe en el formato requerido por el endpoint. Obtén una credencial nueva mediante el proceso aprobado si ha caducado. Nunca pegues credenciales en tickets, registros ni comandos de diagnóstico.

Para 403, confirma que la identidad autenticada tenga el rol o permiso necesario sobre el recurso. Los propietarios del sitio deben inspeccionar las reglas de autorización, las restricciones de IP, las políticas del WAF o la CDN y los controles de acceso específicos del entorno. Un 403 no se soluciona cambiando la URL, salvo que la propia URL haya provocado la coincidencia con una política.

4. Comprueba el enrutamiento y el estado del recurso

Para 404, verifica la ortografía, las mayúsculas y minúsculas cuando sean relevantes, los prefijos de ruta, el nombre de host, el entorno de despliegue y el comportamiento de la ruta final. Comprueba el enrutamiento de la aplicación, el reenvío del reverse proxy y si el recurso existe realmente.

Para 410, interpreta la respuesta como una señal de eliminación intencionada, salvo que el propietario confirme lo contrario. Actualiza los enlaces o clientes al recurso de sustitución si existe; no te limites a repetir la misma URL.

5. Comprueba el tamaño de la solicitud

Para 413, mide el cuerpo de la solicitud o la carga y compáralos con los límites documentados. Comprueba cada capa relevante —cliente, reverse proxy, CDN/WAF y aplicación—, ya que el límite más pequeño puede generar la respuesta. Primero, reduce la carga o utiliza el mecanismo de carga documentado.

Aumentar un límite requiere autorización, una revisión de capacidad y cambios de configuración coordinados. Puede incrementar el consumo de recursos y la exposición al abuso mediante solicitudes grandes.

6. Gestiona la limitación de frecuencia de forma segura

Para 429, detén los reintentos innecesarios, reduce la concurrencia y la frecuencia de las solicitudes, y respeta Retry-After cuando esté presente. Utiliza un backoff exponencial acotado y caché en el cliente cuando corresponda.

Los propietarios del sitio deben identificar el alcance del límite —usuario, token, IP, ruta o servicio— y revisar la configuración de cuotas y los patrones de tráfico antes de cambiarlo.

7. Identifica la capa que responde

Los propietarios del sitio deben correlacionar la marca de tiempo, la ruta, el método y el ID de solicitud con los registros de la aplicación, el reverse proxy, la CDN y la seguridad. Si no existe ninguna solicitud coincidente en el origen, investiga primero la CDN, el WAF o el proxy.

Compara las cabeceras de respuesta, el formato del cuerpo y los identificadores del servidor entre una prueba aprobada directamente contra el origen y la ruta pública. No omitas los controles de seguridad sin autorización.

8. Repite la prueba del cambio específico

Repite la prueba solo después de cambiar la solicitud o la regla responsable de la respuesta. Confirma tanto el caso correcto esperado como los casos de error relevantes, como una identidad no autorizada, una carga demasiado grande o una solicitud enviada con demasiada frecuencia. Supervisa las tendencias de respuestas 4xx después de un despliegue o de cambios en las políticas para detectar regresiones.

Prevención y cómo verificar la solución

• Documenta los métodos de los endpoints, los campos obligatorios, los requisitos de autenticación, los códigos de respuesta, los límites de tamaño de las solicitudes y el comportamiento de los límites de frecuencia.
• Mantén actualizados los enlaces internos y externos, y prueba las redirecciones o eliminaciones cuando cambien las rutas.
• Utiliza pruebas automatizadas para los límites de autorización, los métodos compatibles, las entradas con formato incorrecto y los conflictos de estado de los recursos.
• Valida los tamaños de las solicitudes y el comportamiento de reintento de los clientes antes de publicar en producción.
• Usa backoff acotado, caché y deduplicación de solicitudes para los clientes que puedan encontrar respuestas 429.
• Supervisa las tasas de 4xx por ruta, estado, cliente y capa que responde para poder distinguir entre enlaces rotos, regresiones de permisos y cambios en los clientes.
• Mantén disponibles los ID de correlación y los registros saneados en las capas de aplicación, proxy, CDN y seguridad.

Preguntas frecuentes