¿Qué es la limitación de frecuencia de la API?

La limitación de frecuencia de la API restringe las solicitudes que un cliente puede realizar dentro de un período definido o un presupuesto de recursos. Un servicio puede aplicar límites por cuenta, credencial, endpoint, dirección u otro criterio de uso.

Un limitador de frecuencia cuenta las solicitudes, o un costo ponderado por solicitud, frente a una cuota que pertenece a una partición, como una cuenta, una credencial, una dirección IP o un endpoint, y a una misma solicitud se le puede aplicar más de una política. El algoritmo de conteo determina cómo se tratan las ráfagas. Un contador de ventana fija se reinicia en cada límite de ventana, por lo que un cliente puede consumir la cuota de una ventana justo antes del reinicio y la de la siguiente justo después. Una ventana deslizante suaviza ese efecto, por ejemplo, sumando el conteo de la ventana anterior ponderado según la parte de esa ventana que aún se superpone. Un depósito de tokens añade tokens a una tasa constante hasta una capacidad fija, y esa capacidad limita la ráfaga que admite. Un depósito con fugas se vacía a una tasa constante; la implementación de NGINX retrasa de forma predeterminada las solicitudes excedentes y las rechaza cuando superan el tamaño de ráfaga configurado. Un servicio puede ejecutar varios limitadores en paralelo, por ejemplo, una tasa de solicitudes, un límite de solicitudes concurrentes y un presupuesto independiente para operaciones costosas o que crean contenido, de modo que mantenerse por debajo de un límite no significa mantenerse por debajo de todos. Cuando se rechaza una solicitud, la respuesta puede indicar cuánto tiempo esperar, lo que permite a los clientes distribuir sus reintentos en lugar de volver todos a la vez.

HTTP define el estado 429 Too Many Requests para una solicitud sujeta a limitación de frecuencia, y la respuesta puede incluir un encabezado Retry-After, pero ninguno de los dos está garantizado. GitHub documenta que puede responder con 403 o 429, junto con un encabezado x-ratelimit-remaining con valor 0 o un mensaje de error que indica que se superó un límite de frecuencia, y el módulo limit_req de NGINX rechaza las solicitudes con 503 a menos que se configure limit_req_status. Detecta la limitación a partir de los códigos de estado, los encabezados y el cuerpo del error que documenta la API, no solo a partir de 429.
Retry-After indica un número de segundos que esperar después de recibir la respuesta o una fecha HTTP, por lo que el cliente debe interpretar ambas formas. Algunas API informan del tiempo de espera en otro lugar: GitHub también usa x-ratelimit-reset, un instante expresado en segundos desde la época Unix en UTC, y otros servicios incluyen un retraso en el cuerpo JSON del error. Lee el tiempo de espera en el lugar y en la unidad que documenta la API.
No existe un estándar definitivo para comunicar la cuota restante. Los campos de encabezado RateLimit y RateLimit-Policy son un borrador de Internet del IETF (revisión 11, de mayo de 2026), no un RFC, y las API en uso emplean nombres específicos de cada proveedor, como x-ratelimit-remaining. El borrador indica a los clientes que no traten la cuota comunicada como una garantía y da prioridad a Retry-After cuando una respuesta incluye ambos.
La cuota informada puede ser inexacta, porque los limitadores que se ejecutan en muchos servidores comparten sus contadores o usan aproximaciones. GitHub señala que el conteo restante puede variar entre respuestas cuando las solicitudes se procesan en varias regiones y desaconseja una lógica que dependa de un conteo restante exacto; Amazon API Gateway describe sus límites de frecuencia y cuotas como objetivos sujetos al mejor esfuerzo, no como máximos garantizados. Regula el ritmo de las solicitudes a partir de los valores informados, pero sigue manejando las respuestas de limitación incluso cuando la última respuesta indicaba que quedaba cuota.

Los límites de frecuencia condicionan cualquier cliente que envíe solicitudes de forma masiva o en paralelo, como las importaciones, los bucles de consulta periódica, las tareas por lotes y la lógica de reintentos. Consulta los límites documentados de la API y su respuesta de limitación antes de crear el cliente; después, espera al menos el tiempo que indique esa respuesta, añade una variación aleatoria para que los ejecutores paralelos no reintenten todos al mismo tiempo y limita el número de intentos. Cuando una respuesta de limitación no indique una espera, usa la alternativa que documenta la API o, en su defecto, un retraso que crezca exponencialmente con cada intento hasta un máximo. Reintentar de inmediato añade carga y puede prolongar la limitación, y algunos proveedores, entre ellos GitHub, advierten que pueden bloquear una integración que siga enviando solicitudes mientras está limitada.

Transloadit limita la frecuencia de las solicitudes a su propia API y documenta los límites actuales en su página de limitación de frecuencia. Una solicitud rechazada por superar un límite de creación o concurrencia devuelve un error JSON que indica un tiempo de espera recomendado en segundos, y los SDK oficiales de Transloadit ya aplican esa espera y reintentan la solicitud.

El tiempo indicado es una espera recomendada antes del reintento: la documentación dice que no garantiza que haya capacidad disponible una vez transcurrido. La misma página describe un límite independiente de alta frecuencia, y la respuesta mostrada para ese límite no incluye un tiempo de espera, por lo que el cliente que la maneja debe establecer su propia espera entre reintentos.

Explora las capacidades de la plataforma de Transloadit

¿Qué es la limitación de frecuencia de la API?

Cómo funciona la limitación de frecuencia de la API

Datos clave

Cuándo es relevante la limitación de frecuencia de la API

Cómo ayuda Transloadit con la limitación de frecuencia de la API

Fuentes

Convierte tus conocimientos sobre multimedia en un pipeline funcional