Límites de frecuencia

La API pública aplica un contenedor de solicitudes con ventana deslizante de un minuto a cada clave de API o token de acceso de OAuth. Crear más claves para eludir un límite no está permitido y puede dar lugar a restricciones en las credenciales o en la cuenta.

Límites por plan#

Una credencial cuya cuenta no tenga un plan de pago activo recibe 403 subscription_required antes de que se le asigne capacidad de límite de frecuencia. Make Agent Fast puede introducir límites más bajos específicos para ciertos endpoints en operaciones especialmente costosas; cuando eso ocurra, la referencia del endpoint los indicará de forma explícita.

Una respuesta con límite de frecuencia#

Cuando el contenedor se agota, la API devuelve 429 rate_limit_exceeded con:

HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-Request-Id: 6c0b2f2e-...
Content-Type: application/json

Retry-After es el número mínimo de segundos que debes esperar. Cada respuesta autenticada incluye además X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (una marca de tiempo Unix), de modo que las aplicaciones pueden limitar su ritmo antes de recibir un 429.

Implementación de reintentos#

Usa un retroceso exponencial con jitter aleatorio, respeta un Retry-After mayor y limita el número total de intentos.

async function requestWithRetry(url: string, init: RequestInit, attempts = 4) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status !== 429 && response.status < 500) return response;

    if (attempt === attempts - 1) return response;
    const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1_000;
    const exponential = 500 * 2 ** attempt;
    const jitter = Math.random() * 250;
    await new Promise((resolve) =>
      setTimeout(resolve, Math.max(retryAfter, exponential + jitter)),
    );
  }
  throw new Error("unreachable");
}

En POST, PATCH y DELETE, conserva la misma Idempotency-Key válida en todos los reintentos por errores de red o de servidor. Una nueva clave de idempotencia puede repetir un efecto secundario que ya se completó.

Reduce el volumen de solicitudes#

• Almacena en caché las lecturas de cuenta, sitio y configuración que no necesiten estar actualizadas en tiempo real.
• Solicita hasta 100 registros por página en lugar de pedir repetidamente páginas muy pequeñas.
• Procesa los eventos de webhook en lugar de consultar periódicamente conversaciones, leads o difusiones.
• Limita la concurrencia de los workers por clave de API; una ráfaga de muchas invocaciones serverless comparte el mismo contenedor.
• Usa claves distintas para servicios distintos con fines de aislamiento y auditoría, no para multiplicar la capacidad de una misma carga de trabajo.

Tabla de reintentar y no reintentar#

Si una carga de trabajo sostenida supera legítimamente el contenedor de tu plan, reduce las consultas periódicas, agrupa el trabajo en lotes o contacta con soporte aportando ID de solicitud representativos y el tráfico esperado, en lugar de añadir un bucle de reintentos sin límite.