Qué significa un 429 Too Many Requests y de quién es la culpa

Un 429 Too Many Requests es el único código de estado que trata de usted y no del servidor ni de aquello que pidió. Nada se ha roto, nada falta, y tiene permiso para estar aquí. Simplemente ha preguntado más a menudo de lo que alguien consideró razonable, y la respuesta es una negativa con un reloj pegado.

Todo lo demás en el rango 4xx describe una petición concreta: esta estaba malformada, esta no traía credenciales, esta no nombraba nada. Un 429 describe un patrón. Es el servidor hablando de su comportamiento a lo largo de una ventana de tiempo, y por eso puede llegar como respuesta a una petición perfectamente correcta que habría funcionado hace diez minutos.

El único error en el que reintentar lo empeora

La mayoría de los errores premian un reintento. Un 503 a menudo se aclara al segundo intento, y con un 500 vale la pena una recarga por si pilló un mal momento. El instinto suele acertar, y aquí se equivoca justo.

Un limitador de tasa cuenta peticiones. Un reintento es una petición. Machacar un servicio que acaba de decirle que vaya más despacio alarga la ventana en la que le tienen retenido y, en servicios que escalan, convierte un límite de sesenta segundos en una hora o en un bloqueo que alguien tiene que levantar a mano. El bucle de reintentos ingenuo, el que no lleva pausa dentro, es la forma en que un estrangulamiento breve se convierte en una caída que parece culpa del otro lado.

Así que un 429 es el error en el que no hacer nada es la decisión activa. Espere a que pase la ventana y luego vaya otra vez, una vez.

Las cabeceras que dicen cuándo volver

Un 429 normalmente lleva Retry-After, dando o un número de segundos o una fecha:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1789412400

Retry-After es la estándar y la única en la que puede confiar. La familia X-RateLimit-* es una convención y no una especificación: muy usada, escrita de forma distinta por servicios distintos, y digna de leerse cuando está, porque le dice la forma del límite y no solo el próximo momento en que puede llamar.

Esas cabeceras son la diferencia entre replegarse bien y adivinar. Si está escribiendo cualquier cosa que hable con una API de forma programada, léalas: a un servicio que dijo sesenta segundos y recibe un reintento cada segundo se le está pidiendo ciento veinte veces que atienda peticiones que ya ha rechazado.

Cuando el tráfico no era suyo

Lo incómodo de un 429 es que lo que se cuenta rara vez es una persona. Es una dirección IP, una clave de API, una cuenta o una sesión, y cada una de esas cosas cubre a más de uno de ustedes.

Una oficina detrás de una sola dirección, una cafetería, un operador móvil haciendo NAT a escala de operador, un pipeline de CI compartiendo clave con un equipo, un compañero probando un script contra el mismo endpoint con las mismas credenciales. Todo eso produce un 429 para alguien que no hizo nada raro, y nada de ello se ve desde la página de error.

De ahí sale la prueba útil. Si un 429 le sigue entre redes, es su cuenta o su clave; si desaparece con datos móviles, era la dirección desde la que venía. Es la misma pregunta que distinguir su bug de la caída de ellos, hecha sobre un límite en lugar de sobre un fallo.

Le pueden limitar sin que vea nunca un 429

Nada obliga a un servicio a usar este código. Muchos devuelven un 403 para que el estrangulamiento parezca una decisión de permisos, algunos devuelven un 503 porque desde fuera “ahora no” es cierto igualmente, y una CDN delante de una aplicación responderá a menudo con su propia elección en lugar de con la de la aplicación.

Así que un 429 es, en cierto modo, una buena noticia: es un servicio siendo concreto con usted. Su ausencia no es prueba de que no le estén limitando, y si un 403 o un 503 aparece solo bajo carga y solo desde una dirección, un limitador es lo que hay que sospechar diga lo que diga el código.

Si la API es suya

La pregunta que conviene responder antes de cualquier ajuste es qué capa está contando. Un límite en su aplicación, uno en nginx y uno en la CDN son tres conjuntos de números distintos, y aquel contra el que chocan sus usuarios normalmente no es el que usted ha estado mirando.

Luego mande las cabeceras. Un 429 sin Retry-After es un servicio que se niega a decir cuándo, lo que deja a cada cliente inventarse un backoff, y los que se inventan son peores que el número que usted les habría dado. Ser concreto no cuesta nada.

Y tenga cuidado con qué cuenta el límite. Los límites por IP castigan a oficinas y redes compartidas por el comportamiento de una sola persona dentro, que es un ticket de soporte que llega como “su sitio está roto para todo nuestro equipo”. Los límites por cuenta o por clave son más difíciles de implementar y mucho más fáciles de explicar.

Por qué un 429 es difícil de reconstruir después

Para cuando alguien se lo cuenta, la ventana ha pasado y la petición funciona. Lo que la hizo fallar no fue la petición sino su compañía: las otras noventa y nueve que llegaron en el mismo minuto, la mayoría de otra persona, ninguna de ellas delante de usted ahora.

El registro de red es lo que hace investigable un 429: la petición que falló, el minuto exacto, y las cabeceras de respuesta diciendo qué límite se tocó y cuánto le quedaba por correr. Esa es la diferencia entre un informe que alguien puede cruzar con el log de un limitador y un mensaje diciendo que el sitio dejó de funcionar un rato esta mañana.

En un párrafo

Un 429 Too Many Requests significa que ha preguntado demasiadas veces, lo que lo convierte en el único código de estado sobre su comportamiento en lugar de sobre el servidor o el recurso. Es además el único error en el que reintentar es activamente contraproducente, porque un reintento es otra petición que el limitador cuenta: lea Retry-After, espere, y luego vaya una vez. El tráfico que se cuenta a menudo no es el suyo, ya que los límites se aplican a direcciones y claves que cubren oficinas y equipos enteros, y un móvil con datos le dirá con cuál de los dos está tratando. Si la API es suya, averigüe qué capa cuenta, mande siempre Retry-After, y prefiera limitar una clave antes que una dirección, para que una persona no pueda dejar fuera a todo un edificio.