Rate Limit
Un rate limit es el tope de peticiones o tokens que una API permite procesar en un intervalo de tiempo, protegiendo la infraestructura y repartiendo la capacidad entre usuarios; superarlo devuelve un error HTTP 429.
Un rate limit es el límite máximo de peticiones o de tokens que una API acepta procesar dentro de una ventana de tiempo, normalmente por minuto. Cuando lo superas, la API rechaza la petición con un error 429 Too Many Requests en lugar de atenderla. Es el mecanismo con el que proveedores como Anthropic protegen su infraestructura y reparten la capacidad de cómputo de forma justa entre todos los clientes.
Cómo funciona en la API de Claude
La API de Claude no impone un único límite, sino varios que se miden en paralelo. Los principales son:
- RPM (requests per minute): número de peticiones que puedes enviar por minuto.
- ITPM (input tokens per minute): tokens de entrada procesados por minuto.
- OTPM (output tokens per minute): tokens de salida generados por minuto.
Basta con exceder uno de ellos para recibir un 429. Los límites concretos dependen de tu tier de uso (nivel), que sube automáticamente a medida que acumulas gasto e historial de pago. Un tier inicial tiene topes bajos; los tiers superiores permiten volúmenes de producción mucho mayores.
Las respuestas de la API incluyen cabeceras anthropic-ratelimit-* que informan del límite, de cuánto queda y de cuándo se resetea el contador. Cuando llega un 429, suele venir con una cabecera retry-after que indica los segundos que debes esperar antes de reintentar.
Por qué importa
Si construyes sobre la API, los rate limits marcan la diferencia entre una aplicación estable y una que falla bajo carga. Ignorarlos provoca errores en cascada justo cuando más tráfico tienes. La práctica estándar es implementar reintentos con backoff exponencial: al recibir un 429, esperas, reintentas, y si vuelve a fallar duplicas el tiempo de espera. Los SDK oficiales de Anthropic ya incluyen esta lógica por defecto.
También conviene diseñar pensando en el consumo: agrupar peticiones, cachear resultados y controlar el tamaño de las respuestas. Aquí el prompt caching ayuda a reducir tokens de entrada facturados y procesados. Si quieres aprender a construir sobre la API de Claude respetando estos límites desde el primer día, conviene practicar con casos reales de manejo de errores y throttling.
Rate limit no es lo mismo que cuota ni que coste
Es un error frecuente confundir tres conceptos:
- Rate limit: velocidad máxima (por minuto). Se resetea constantemente.
- Cuota o límite de gasto: tope de dinero que puedes gastar en un periodo (mensual, por ejemplo). No tiene que ver con la velocidad.
- Coste por token: lo que pagas por cada token, independiente de cuántos puedas enviar por minuto.
Puedes tener saldo de sobra y aun así recibir 429 por ir demasiado rápido; y al revés, ir muy lento y agotar tu presupuesto. Son controles independientes.
Errores comunes
- No leer las cabeceras de rate limit y descubrir el tope solo cuando la app cae.
- Reintentar de forma agresiva sin backoff, lo que empeora el 429 en lugar de resolverlo.
- Suponer que subir de tier es inmediato: depende de historial de uso y pago.
- Contar solo peticiones e ignorar los límites de tokens, que suelen ser los primeros en saltar con prompts largos.
En resumen: trata los rate limits como una restricción de diseño, no como un obstáculo puntual. Una arquitectura que los anticipa escala; una que los ignora se rompe.
Preguntas frecuentes
¿Qué significa el error 429 en la API de Claude?
El 429 (Too Many Requests) indica que has superado un rate limit: demasiadas peticiones o demasiados tokens por minuto. La respuesta suele incluir una cabecera retry-after con los segundos que debes esperar antes de reintentar.
¿Cómo puedo subir mis rate limits en Claude?
Los límites están ligados a tu tier de uso, que sube automáticamente a medida que acumulas historial de pago y gasto en la plataforma. Para volúmenes altos de producción también puedes contactar con Anthropic para acuerdos específicos.
¿La diferencia entre rate limit y cuota de gasto?
El rate limit controla la velocidad (peticiones o tokens por minuto) y se resetea constantemente. La cuota de gasto limita el dinero total en un periodo. Son controles independientes: puedes tener saldo y aun así recibir un 429 por ir demasiado rápido.
¿Cómo evito que los rate limits rompan mi aplicación?
Implementa reintentos con backoff exponencial, lee las cabeceras anthropic-ratelimit-* para anticipar el tope, agrupa peticiones y usa prompt caching para reducir tokens procesados. Los SDK oficiales ya incluyen la lógica de reintento por defecto.