Cómo funcionan los límites de uso de la API de Vista Social

Vista Social aplica límites de uso para que la plataforma sea rápida y justa para todos los espacios de trabajo. Este artículo explica cuáles son los límites, cómo saber cuándo te estás acercando a uno y qué hacer si lo alcanzas.

Si solo tienes un minuto, este es el resumen:

• Límite predeterminado: 60 solicitudes por minuto, por integración. La integración MCP (ChatGPT / Claude / Cursor / etc.) tiene un límite más alto de 180 solicitudes por minuto.
• Cada integración tiene su propio presupuesto. Usar Zapier no ralentiza tus llamadas directas a la API (ni al revés).
• Te decimos exactamente dónde estás en cada respuesta, con tres encabezados: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• Si te pasas, recibes una respuesta HTTP 429 con un encabezado Retry-After que indica cuántos segundos debes esperar.

Eso cubre el 90% de lo que la mayoría necesita. El resto del artículo completa los detalles.

Dónde se aplican los límites de uso

Cada fila es un presupuesto independiente. Un espacio de trabajo que usa Zapier y llama directamente a la API REST y conecta un asistente de IA compatible con MCP tiene tres presupuestos independientes, no uno compartido. Elige la integración adecuada para cada tarea y rara vez te quedarás sin margen.

Los planes Enterprise pueden aumentar el límite por minuto de las integraciones. Si tu negocio necesita un límite más alto, contacta a tu account manager de Vista Social: podemos ampliarlo por espacio de trabajo.

Cómo leer los encabezados de límite de uso

Cada respuesta de /api/integration/* (incluidas las exitosas) incluye tres encabezados que describen tu bucket actual:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1716480123

Si creas automatizaciones con la API de Vista Social, la forma más sencilla de no tener problemas es leer X-RateLimit-Remaining y hacer una pausa cuando baje (por ejemplo, por debajo de 5) hasta que pase X-RateLimit-Reset.

Los valores anteriores son los predeterminados; los valores reales dependen de tu suscripción. Confía siempre en los encabezados, no en la documentación.

Cuando superas el límite

Recibirás una respuesta HTTP 429 Too Many Requests.

Encabezados de la respuesta:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1716480123
Retry-After: 24
Content-Type: application/json

Cuerpo de la respuesta:

{
  "error": "You are going too fast, please slow down. 60 requests are allowed every minute per integration.",
  "errorValues": { "value1": 60 }
}

Qué hacer:

1. Lee Retry-After. Ese número (en este ejemplo, 24) es la espera, en segundos, hasta que tu bucket se haya recargado lo suficiente para aceptar la siguiente solicitud.
2. Espera al menos ese tiempo antes de reintentar. Los clientes HTTP habituales (axios, requests de Python, Postman, etc.) respetan Retry-After automáticamente cuando están configurados para reintentar ante un 429.
3. No reintentes antes de lo que indica Retry-After. Hacerlo solo genera más errores 429 y activa las alertas por infracciones repetidas que se describen más abajo.

Infracciones repetidas

Superar el límite una o dos veces es normal, por ejemplo, cuando un script se inicia y calienta su caché. Pero si tu integración sigue superando el límite, tomamos medidas:

Si tu clave se desactiva, corrige el problema de fondo (normalmente un bucle descontrolado en tu script) y contacta a soporte para reactivarla. El contador se reinicia una hora después de tu última infracción.

Notas por integración

API REST directa

El bucket predeterminado de 60 solicitudes/minuto. Los endpoints están en https://vistasocial.com/api/*; consulta la referencia completa en apidocs.vistasocial.com. Autentícate con tu clave de API en el encabezado x-api-key. No hace falta indicar la integración.

Zapier / Make / n8n

Cada plataforma funciona en su propio bucket. Envía el encabezado api_client en tus solicitudes personalizadas para que sepamos de qué integración viene la llamada: api_client: zapier, api_client: make o api_client: n8n. (Para n8n también puedes enviar User-Agent: n8n, que también reconocemos). Sin una de estas indicaciones, la solicitud cae en el bucket de la API REST directa y comparte presupuesto con tus propias llamadas a la API.

(Si usas nuestras apps prediseñadas de Zapier / Make / n8n, esto se hace automáticamente).

MCP (ChatGPT, Claude, Cursor, etc.)

Las integraciones MCP tienen dos límites que se suman:

• Límite por minuto (este artículo): 180 solicitudes/minuto en el canal mcp. Es más alto que el límite predeterminado de 60/min de las otras integraciones, porque los asistentes de IA suelen enviar solicitudes en ráfagas y no siempre se ajustan al límite estándar.
• Límite de ráfaga por herramienta (dentro de MCP): cada herramienta tiene además su propio límite de ráfaga a corto plazo. Las herramientas costosas como generateImage y generateVideo tienen un límite más bajo (por ejemplo, 10 de ráfaga / 5 por minuto para generateImage); las herramientas ligeras usan un valor predeterminado generoso. Cuando una herramienta supera su propio límite, el asistente de IA ve un error estructurado de "rate limited" en la respuesta y se le indica que espere antes de reintentar.

No necesitas configurar nada para ninguno de los dos: ambos se aplican automáticamente. El límite por herramienta entra en juego sobre todo con asistentes que intentan generar grandes lotes de contenido multimedia en una sola conversación; el uso normal y variado de herramientas rara vez lo alcanza.

Apps OAuth

El tráfico autenticado con OAuth usa tokens bearer en lugar de claves de API, pero se aplica el mismo presupuesto de 60 solicitudes/minuto, limitado al espacio de trabajo que otorgó la autorización.

Preguntas frecuentes

"Estoy muy por debajo de 60 solicitudes por minuto, ¿por qué recibo errores 429?"

Revisa estos puntos:

1. ¿Otras integraciones comparten la misma clave de API? Si varios scripts comparten una clave, comparten el bucket. Usa una clave de API distinta para cada integración siempre que puedas.
2. ¿Estás enviando api_client? Un zap de Zapier y un script personalizado que usan la misma clave de API sin el encabezado api_client caen en el mismo bucket direct. Envía el encabezado desde Zapier para separarlos.
3. ¿Envías ráfagas al inicio del minuto? La ventana se reinicia al comienzo de cada ciclo de "primera solicitud", no en los cambios de minuto del reloj. Distribuye las solicitudes de forma uniforme dentro del minuto en lugar de enviarlas todas en el primer segundo.

"¿Pueden aumentar mi límite de uso?"

Para espacios de trabajo con un plan de pago de Vista Social, sí: contacta a tu account manager o abre un ticket y lo revisaremos. A los espacios de trabajo gratuitos no se les puede aumentar el límite, pero pueden suscribirse en cualquier momento.

"¿Las operaciones masivas cuentan como una solicitud o como varias?"

Una solicitud HTTP = una unidad, sin importar cuántos datos lleve. Un POST /publishing/posts que programa en 10 perfiles cuenta como 1 solicitud, no 10.

"¿Las solicitudes GET cuentan en el mismo bucket que POST / PUT?"

Sí, el límite es por solicitud, no por tipo de operación. Leer y escribir comparten el mismo presupuesto de 60 solicitudes/minuto en cada integración.

"¿Dónde veo mi uso actual del límite?"

En los encabezados de respuesta de cada llamada a la API. Hoy no ofrecemos un panel para esto; los encabezados son la fuente de verdad.

"¿Y si mi cliente de API no admite Retry-After automáticamente?"

Lee Retry-After de la respuesta 429 y llama a sleep(N) (o equivalente) antes de reintentar. Todos los clientes HTTP lo permiten; simplemente no es automático en todos.

¿Sigues con problemas?

Contacta al soporte de Vista Social con:

• El nombre de tu espacio de trabajo o el ID de la entidad raíz
• La integración que se está limitando (zapier, mcp, etc.)
• Un ejemplo del cuerpo de una respuesta 429 (para verificar qué bucket está implicado)
• La marca de tiempo del 429 más reciente

A partir de ahí lo rastreamos.