Límite de frecuencia (rate limit)

Límite de frecuencia o cuota: averigua cuál te ha frenado

Los dos llegan como una petición rechazada, y algunos proveedores devuelven el mismo código de estado para ambos, así que el error por sí solo rara vez te dice cuál ha sido. Merece la pena aclararlo antes de tocar código, porque las soluciones van en direcciones opuestas.

• Un límite de frecuencia cuenta peticiones por una ventana corta. La solución es ir más despacio: espaciar las peticiones, ponerlas en cola y, cuando la respuesta trae una cabecera Retry-After, esperar ese tiempo antes de reintentar.
• Una cuota cuenta el uso total —peticiones, créditos, mensajes, tokens— durante un día o un mes. Esperar unos segundos no cambia nada; las opciones son esperar al reinicio, ampliar el límite o gastar menos.
• Un límite de concurrencia fija cuántas peticiones pueden estar en curso a la vez, por despacio que lleguen. Aparece cuando el trabajo se reparte en paralelo, y es fácil confundirlo con un límite de frecuencia.

Comprueba también contra qué se cuenta el límite: una clave de API, una cuenta o la dirección desde la que llegan las peticiones. Eso decide si una segunda clave cambiaría algo.

Una cuota que agotamos sin darnos cuenta

AgentCeres, el AI Growth Officer de agentceres.com, opera agentes que buscan en la web mientras trabajan, y esas búsquedas pasaban por una API de búsqueda con claves del plan gratuito de 1.000 créditos al mes. En septiembre de 2026 descubrimos que la clave que compartían la mayoría de nuestros contenedores de agentes estaba en 1.002 de 1.000. Todas las búsquedas web de esos espacios de trabajo llevaban tiempo fallando y nada lo mostraba: los agentes llamaban directamente al proveedor de búsqueda, así que ese tráfico no pasaba por nada nuestro que lo contara.

La cifra de uso engañaba de una forma que vale la pena recordar. Un contador que se detiene en su tope es un mínimo, no una medición: una vez agotada la clave, las búsquedas siguientes fallaban en lugar de contarse, así que el número que veíamos se quedaba corto frente a la demanda real. Después de mover la carga a claves con margen, un día completo de tráfico sin ningún tope llegó a unos 153 créditos, unos 4.600 al mes: alrededor de cuatro veces el uso mensual que podíamos ver mientras la clave estaba topada.

La segunda lección llegó al construir la comprobación. El endpoint de uso del proveedor también tiene un límite de frecuencia, y ese límite se cuenta por la dirección desde la que llegan las peticiones y no por la clave: en cuanto una comprobación lo activó, cinco claves distintas devolvieron 429 a la vez. Un script que reintentara clave por clave solo habría hundido más el agujero, así que el nuestro se detiene en el primer 429 e informa de que no pudo tomar una lectura, y lo trata como un fallo, nunca como un resultado limpio.

Diseñar para los límites con los que te vas a topar

Da por hecho que todo servicio al que llamas te rechazará en algún momento, y decide de antemano cómo lo verá la persona que usa tu producto. Un rechazo que aparece como un mensaje claro cuesta un poco de confianza. Un rechazo que aparece como un resultado discretamente peor cuesta mucho más, porque nadie sabe que hay algo que arreglar. Por qué mi app dejó de enviar correos recorre el mismo fallo en un proveedor de correo, donde el rechazo llegó con la apariencia de otro error.

Tres hábitos cubren casi todo. Espera y reintenta ante un límite de frecuencia, respetando Retry-After, pero nunca reintentes de forma automática una acción que quizá ya ocurrió, como un pago o un mensaje enviado. Registra el uso de cada servicio medido en un sitio que de verdad mires, con una alerta mucho antes del tope y no al llegar a él. Y trata una lectura que falta como una alarma: la comprobación que no puede ejecutarse es la que esconde la caída.