HTTP 429 Too Many Requests: qué significa y cómo solucionarlo

Qué significa este error y cómo reconocerlo

• Un navegador, cliente de API, herramienta de monitorización o comprobador recibe 429 Too Many Requests.
• La respuesta puede afectar a una URL, ruta de API, método HTTP, dirección IP, cuenta o cliente concretos, en lugar de a todo el sitio.
• Las solicitudes pueden volver a funcionar después de un tiempo, lo que es coherente con un rate limit temporal.
• La respuesta puede incluir Retry-After u otras cabeceras relacionadas con el rate limiting.
• El DNS puede resolver y TLS puede completarse correctamente porque la solicitud llegó a un endpoint que habla HTTP; esas comprobaciones no demuestran que la solicitud esté permitida en la capa de aplicación.
• Distintos clientes o redes pueden recibir resultados diferentes cuando el límite está asociado a una IP, identidad, token o sesión.

Causas principales, ordenadas por probabilidad

1. Se superó un límite de solicitudes. La aplicación, la API gateway o el servidor web pueden limitar las solicitudes por dirección IP, cuenta, sesión, clave de API, ruta u otra identidad del cliente.
2. Un proxy, una CDN o un WAF aplicó su propia política. Un intermediario puede devolver 429 antes de que la solicitud llegue al servidor de origen.
3. El tráfico automatizado envía solicitudes demasiado rápido. Los crawlers, las comprobaciones de monitorización, los scripts, los reintentos o los workers paralelos pueden activar un límite aunque las solicitudes individuales parezcan válidas.
4. Un cliente reintenta sin backoff. Los reintentos repetidos después de fallos pueden mantener al cliente dentro de la ventana del límite o intensificar la carga.
5. Una configuración o un despliegue modificó el umbral efectivo. Una regla reciente, un cambio de enrutamiento, una integración de autenticación o una política del proxy puede haber alterado qué solicitudes se contabilizan o limitan.
6. El límite es intencionado, pero el flujo de trabajo del cliente no es compatible con él. Por ejemplo, un proceso por lotes puede necesitar dosificar las solicitudes, reutilizar conexiones o contar con una cuota de solicitudes aprobada, en lugar de realizar reintentos inmediatos y repetidos.

Cómo solucionarlo

Para visitantes y consumidores de API

1. Detén las actualizaciones rápidas, las solicitudes paralelas y los reintentos automáticos mientras investigas.
2. Comprueba las cabeceras de respuesta en busca de Retry-After. Si está presente, espera el retraso o el momento indicado antes de volver a intentarlo.
3. Reintenta la URL o el endpoint de API exactos con el mismo método después del retraso. No cambies de método ni varíes las solicitudes repetidamente solo para eludir el límite.
4. Si controlas el cliente, usa reintentos acotados con exponential backoff y jitter, y respeta la cuota de solicitudes documentada por el servicio. Evita reintentar solicitudes que no sea seguro repetir, salvo que la API defina cómo deben reintentarse.
5. Comprueba si el problema afecta a un cliente, cuenta, clave de API, red o endpoint concretos. Un resultado diferente en otro cliente no identifica por sí solo la causa.
6. Si el 429 persiste, contacta con el administrador del sitio o de la API e indica el endpoint, el método, la marca de tiempo, las cabeceras de respuesta y una descripción de la frecuencia de las solicitudes. Elimina las cookies, los valores de autorización y los secretos de API de todo lo que compartas.

Para administradores del sitio y desarrolladores

1. Reproduce la respuesta con la prueba autorizada más pequeña que coincida con el método, la URL, la identidad del cliente y la frecuencia de solicitudes afectados. Registra el estado, la marca de tiempo y las cabeceras de respuesta relevantes.
2. Identifica la capa que genera la respuesta. Comprueba los detalles de respuesta de la CDN o el WAF, los logs del proxy inverso, los logs del servidor web y los logs de la aplicación, en el orden que corresponda a tu arquitectura. No des por hecho que la respuesta la generó el origen.
3. Busca en los logs relevantes la misma marca de tiempo, ruta, identificador del cliente y decisión de rate limiting. Determina qué se está contabilizando y qué ventana de límite o política se aplicó.
4. Compara la solicitud afectada con una solicitud normal. Comprueba el método HTTP, el contexto de autenticación, la identidad de origen, la ruta, el recorrido de caché y los cambios recientes de despliegue o configuración.
5. Si el límite es intencionado, mejora las indicaciones para el cliente: devuelve un valor preciso de Retry-After cuando corresponda, documenta las cuotas y asegúrate de que los clientes puedan usar un backoff controlado en lugar de bucles de reintentos rápidos.
6. Si el límite es incorrecto, aplica la corrección autorizada más específica en la capa que generó la respuesta. Valida su efecto en la ruta afectada sin debilitar otras protecciones de seguridad o contra abusos.
7. Repite la misma solicitud con la misma frecuencia y, después, prueba rutas cercanas e identidades de cliente representativas. Confirma que los límites intencionados sigan funcionando y que la respuesta ya no bloquee tráfico legítimo.

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

• Define y documenta las cuotas de solicitudes, el alcance de los límites y el comportamiento de los reintentos para las API y los clientes automatizados.
• Devuelve información útil sobre el rate limiting, incluida Retry-After cuando corresponda y el diseño del servicio lo permita.
• Implementa exponential backoff acotado con jitter en los clientes, en lugar de reintentos inmediatos y repetidos.
• Supervisa las tasas de 429 por ruta, identidad del cliente, red y despliegue para distinguir incrementos generales de abusos aislados o clientes con un comportamiento incorrecto.
• Mantén bajo control de versiones la configuración de rate limiting de la CDN, el WAF, el proxy, el servidor y la aplicación, y revisa los cambios antes de publicarlos.
• Prueba los métodos de API importantes y las rutas públicas después de los despliegues, incluido el comportamiento esperado cuando se alcanza un umbral.
• Conserva suficientes logs sanitizados de solicitudes y decisiones de políticas para relacionar una respuesta 429 con el componente que la generó.

Preguntas frecuentes