Límites de frecuencia

Cuotas por minuto y diarias de la API y del servidor MCP de SociaHive, además de los encabezados y la estrategia de espera.

SociaHive aplica límites de frecuencia por usuario a cada clave de API y token de OAuth. Los límites se agrupan por el tipo de operación, no por el método HTTP: una herramienta que hace una sola lectura consume menos cuota que una que envía el grafo de un flujo generado.

Los cuatro grupos

Grupo	Límite	Ventana	Ejemplos
read	120 solicitudes	1 minuto	`list_flows`, `get_flow`, `list_scheduled_posts`, `get_analytics_overview`, cualquier consulta que no modifique nada
write	30 solicitudes	1 minuto	`create_flow`, `update_node`, `add_edge`, `create_scheduled_post`, `cancel_scheduled_post`
expensive	5 solicitudes	1 minuto	`generate_flow` (generación de flujos con IA), `search_published_media` (búsqueda vectorial), cualquier operación que se apoye en un LLM o en un almacén vectorial
daily	1,000 solicitudes	24 horas	Un tope que se aplica a todos los grupos combinados: protege contra bucles descontrolados

Todos los límites son por usuario (titular de la clave de API o sujeto de OAuth), no por clave. Crear varias claves no multiplica tu cuota.

Respuesta cuando superas un grupo

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json
 
{
  "error": "Rate limit exceeded for read bucket. Retry in 23s.",
  "code": "rate_limit",
  "details": {
    "window": "read",
    "limit": 120,
    "retry_after_seconds": 23
  }
}

El encabezado Retry-After es la referencia: respétalo. details.window te indica qué grupo se superó, por si quieres frenar solo ese tipo de operación.

Espera recomendada

import { SociaHive, SociaHiveError } from '@sociahive/sdk'
 
async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn()
    } catch (err) {
      if (!(err instanceof SociaHiveError) || !err.isRateLimited || attempt === maxRetries - 1) {
        throw err
      }
      const wait = (err.retryAfter ?? Math.pow(2, attempt)) * 1000
      await new Promise(r => setTimeout(r, wait))
    }
  }
  throw new Error('unreachable')
}

No reintentes antes de lo que indica Retry-After: solo chocarás de nuevo con el mismo grupo y gastarás tu tope diario.

Límites específicos del MCP

Además de los cuatro grupos anteriores, el transporte HTTP del MCP añade un tope de 200 sesiones simultáneas. Una “sesión” es una conexión SSE abierta; las inactivas expiran a los 5 minutos. Si abres muchos clientes MCP de corta vida en paralelo (por ejemplo, tareas de CI), cierra la sesión de forma explícita después de cada lote en lugar de esperar la recolección de basura (garbage collection).

El tope diario es el límite que de verdad alcanzarás

Para la mayoría de los usuarios, los grupos por minuto son holgados: 120 lecturas por minuto es más de lo que usa cualquier sesión interactiva. El tope diario de 1,000 solicitudes es el que alcanzan primero los scripts de importación masiva y las tareas cron agresivas.

Si haces trabajo masivo, prefiere los endpoints bulk (posts.bulk, bulk_update_flows) a los bucles de llamadas sueltas: una llamada bulk cuenta como una sola solicitud en tu cuota sin importar cuántas entidades toque.

Qué NO tiene límite de tasa

Los endpoints de autenticación (/api/oauth/*): Cloudflare los limita por separado en el borde
Las páginas de marketing públicas y /api/v1/openapi.json (estático, de solo lectura)
Los webhooks de salida: tienen límites y reglas propios; consulta la guía de webhooks

Límites por plan

Los grupos anteriores son los mismos en todos los planes de pago. Lo que cambia según el plan son los topes de recursos (cuentas conectadas, publicaciones programadas por mes, créditos de IA, etc.), no la tasa de solicitudes a la API. Los topes de recursos de tu plan los devuelven la herramienta MCP whoami y el endpoint REST /api/v1/usage.