Un límite de frecuencia es un tope a cada cuánto puedes llamar a una API — normalmente expresado por segundo, por minuto o por hora. Si te lo pasas, la API deja de contestar, normalmente con un HTTP 429 Too Many Requests.
No es lo mismo que una cuota, y confundir las dos cosas es la forma de llevarse dos sorpresas.
¿Límite de frecuencia o cuota?
| Mide | Se reinicia | Te lo encuentras cuando | |
|---|---|---|---|
| Límite de frecuencia | Llamadas por unidad de tiempo | Continuamente | Vas rápido |
| Cuota | Llamadas por periodo de facturación | Cada mes o cada día | Vas lejos |
Una cuota generosa con un límite de frecuencia apretado significa que puedes hacer un millón de llamadas este mes, pero no en una tarde. Una cuota apretada sin límite de frecuencia significa que puedes quemar el mes en una hora. Lee las dos antes de escribir el bucle.
El límite que te encuentras rara vez es el anunciado
Tres cosas bajan el techo real por debajo del número publicado:
- Límites por endpoint. Un proveedor puede anunciar 100 peticiones por minuto en general y aplicar 10 por minuto en la ruta cara.
- Límites de concurrencia. Algunas API topan las conexiones abiertas simultáneas en lugar de las llamadas por minuto. Diez trabajadores a una llamada cada uno es distinto de un trabajador a diez.
- Cubos de ráfaga. Un cubo de tokens te deja gastar una ráfaga y después te estrangula muy por debajo de la media. La cifra publicada es la tasa de recarga, no lo que consigues en el primer segundo.
Qué hacer cuando recibes un 429
Respeta la cabecera Retry-After si la hay. Si no la hay, retírate exponencialmente y con variación aleatoria — los reintentos a intervalo fijo desde muchos trabajadores se resincronizan y chocan contra el muro juntos.
intento 1 → espera 1s + aleatorio(0–1s)
intento 2 → espera 2s + aleatorio(0–2s)
intento 3 → espera 4s + aleatorio(0–4s)
Lo que no hay que hacer es reintentar inmediatamente en un bucle. En algunos proveedores eso convierte un 429 temporal en un bloqueo más largo.
El fallo que merece que lo tengas en cuenta al diseñar
Un 429 es honesto — te dice lo que pasó. El caso peligroso es un proveedor que responde 200 con datos parciales o vacíos cuando aprietas demasiado, porque nada en tu código lo nota. Eso es un fallo silencioso, y es la razón de que publiquemos una página de estado que nunca se guarda en caché en lugar de una insignia de uptime.
Nuestro propio límite se publica con los precios: un crédito por llamada, y una llamada que no encuentra nada no cuesta nada.