429 Too Many Requests: límites de peticiones, Retry-After y falsas alarmas

Qué significa un 429 y qué viene con él

El 429 está definido en el RFC 6585 como el estado para la limitación de peticiones: el cliente ha enviado demasiadas peticiones en un tiempo dado. La especificación deja dos cosas abiertas a propósito: cómo identifica el servidor al cliente y cómo se cuentan las peticiones. Por eso los límites varían tanto entre servicios.

En la práctica, los servidores cuentan por dirección IP, por clave de API, por sesión, por cuenta o por una combinación de esas, y usan ventanas fijas, ventanas deslizantes o cubos de tokens. Dos ritmos de petición idénticos pueden por tanto estar bien en un endpoint y quedar bloqueados en otro del mismo sitio.

La respuesta lleva las señales que necesitas:

• Retry-After es la estándar. El RFC 9110 admite tanto un número de segundos como una fecha HTTP, y un cliente que se porta bien espera ese tiempo antes de reintentar.
• Cabeceras de límite como RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset, o las variantes más antiguas con X-RateLimit-, muestran el presupuesto y cuándo se reinicia. Son convenciones, no forman parte del RFC 9110, así que consulta la documentación de la API para los nombres exactos.
• El cuerpo debería explicar el límite en términos legibles. Muchas API nombran qué cuota se superó, lo que ahorra mucho adivinar.

Un 429 no es almacenable en caché por defecto, así que los intermediarios no deberían seguir sirviéndolo una vez que se reinicia la ventana.

¿Límite de peticiones o caída real?

Se confunden constantemente, porque los dos se ven como peticiones que fallan. Las pruebas que los distinguen son rápidas:

• El código en sí. Un límite responde 429. Un servidor sobrecargado o en mantenimiento responde 503. Los dos pueden llevar Retry-After, y por eso la gente los mezcla, pero significan cosas distintas: el 429 dice "tú en concreto estás enviando demasiado" y el 503 dice "el servicio en conjunto no puede aceptar trabajo ahora mismo". Ese lado está en la guía del 503.
• El tiempo de respuesta. Los límites rechazan deprisa, normalmente en milisegundos, porque la decisión se toma antes de hacer trabajo real. La sobrecarga responde despacio o agota el tiempo.
• A quién afecta. Un límite golpea a una identidad de cliente. Prueba desde otra dirección IP o con otra clave de API: si eso funciona mientras el cliente restringido sigue fallando, es un límite y no una caída.
• El patrón a lo largo del tiempo. La limitación es periódica y se resuelve sola. Los fallos se agrupan, paran justo cuando se reinicia la ventana y luego vuelven. Una caída no se reanuda con esa puntualidad.
• La correlación con tu propio volumen. Si los fallos empezaron cuando subiste la frecuencia de una comprobación, añadiste procesos en paralelo o lanzaste un proceso por lotes, la causa está en tu lado de la conexión.

Por qué el monitoreo puede provocarse un 429 a sí mismo

El monitoreo es una petición repetida desde un conjunto pequeño de direcciones a la misma URL, que es casi la forma que los limitadores están hechos para detectar. Un intervalo de comprobación muy corto lo empeora, porque comprobaciones cada minuto multiplicadas por muchas URL vigiladas suman rápido frente a un presupuesto por IP. Ejecutar una comprobación desde muchas ubicaciones a la vez también: el origen ve una ráfaga en lugar de un goteo constante, y los límites de ráfaga saltan antes.

La elección de la URL también cuenta. Las páginas de búsqueda, los endpoints de API y todo lo que escribe suelen estar más limitados que una portada estática. Y si el monitoreo y la aplicación comparten una clave de API, los dos compiten por una sola cuota. El resultado es un monitor que informa de que el sitio está fallando cuando el sitio está perfectamente sano y el limitador está haciendo bien su trabajo.

Cómo solucionar un 429

1. Lee las cabeceras de respuesta antes de cambiar nada:

   curl -sS -o /dev/null -D - https://example.com/api/items

   Retry-After y las cabeceras de límite te dicen el presupuesto real, que es mejor que adivinar intervalos.
2. Respeta Retry-After. Reintentar de inmediato alarga el bloqueo en muchas implementaciones. Espera el tiempo indicado.
3. Retrocede de forma exponencial y con variación aleatoria en el código del cliente, para que los clientes concurrentes no se sincronicen y reintenten todos en tropel.
4. Baja el ritmo de peticiones. En monitoreo, pasa el endpoint comprobado a un intervalo más largo, o escalona las comprobaciones para que muchas ubicaciones no disparen en el mismo segundo.
5. Vigila una URL barata y representativa. Un endpoint de salud ligero o la portada te dicen que el sitio está en pie sin gastar la cuota que necesitas para el tráfico real.
6. Exime al cliente de monitoreo en el limitador. Pon las direcciones de los puntos de verificación en la lista de permitidos, o dale al monitoreo su propia clave de API con su propio presupuesto, para que nunca compita con el tráfico de producción.
7. Si el limitador es tuyo, comprueba que el límite es el adecuado. Pregúntate si el presupuesto encaja con el uso real, si es por IP cuando debería ser por cuenta, y si hay proxies compartidos o NAT corporativo poniendo a muchos usuarios detrás de una sola dirección.

Vigilar los 429 sin provocarlos

Los límites suelen aparecer primero para los clientes más activos, lo que significa que los clientes de pago y las integraciones los alcanzan antes que nadie de tu equipo. Una verificación HTTP programada que compruebe el código de estado esperado muestra un 429 como un evento concreto y fechado en lugar de como informes sueltos de "la API va rara", y el horario te dice si el límite es periódico o permanente. Elige el intervalo con cuidado: lo bastante frecuente para notar los problemas pronto y lo bastante suave para que la comprobación no sea nunca lo que dispara el límite. La familia más amplia de negativas, incluidos el 401 y el 403, está en el resumen de los 4xx.