Como funcionam os limites de requisições da API do Vista Social

O Vista Social aplica limites de requisições para manter a plataforma rápida e justa para todos os espaços de trabalho. Este artigo explica quais são os limites, como saber quando você está perto de um deles e o que fazer se atingir um.

Se você só tem um minuto, aqui está o resumo:

• Limite padrão: 60 requisições por minuto, por integração. A integração MCP (ChatGPT / Claude / Cursor / etc.) tem um limite maior, de 180 requisições por minuto.
• Cada integração tem o seu próprio orçamento. Usar o Zapier não deixa mais lentas as suas chamadas diretas à API (nem o contrário).
• Mostramos exatamente onde você está em cada resposta, em três cabeçalhos: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• Se você passar do limite, recebe uma resposta HTTP 429 com um cabeçalho Retry-After informando quantos segundos esperar.

Isso cobre 90% do que a maioria das pessoas precisa. O resto deste artigo completa os detalhes.

Onde os limites se aplicam

Cada linha é um orçamento separado. Um espaço de trabalho que usa o Zapier e chama a API REST diretamente e conecta um assistente de IA compatível com MCP tem três orçamentos independentes, não um único orçamento compartilhado. Escolha a integração certa para cada tarefa e você raramente vai ficar sem margem.

Planos Enterprise podem aumentar o limite por minuto das integrações. Se a sua empresa precisa de um limite maior, fale com o seu account manager no Vista Social: podemos aumentá-lo por espaço de trabalho.

Como ler os cabeçalhos de limite

Toda resposta de /api/integration/* (inclusive as bem-sucedidas) traz três cabeçalhos que descrevem o seu bucket atual:

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

Se você cria automações com a API do Vista Social, a forma mais simples de evitar problemas é ler X-RateLimit-Remaining e pausar quando ele ficar baixo (por exemplo, abaixo de 5) até passar o X-RateLimit-Reset.

Os valores acima são os padrões; os valores reais dependem da sua assinatura. Confie sempre nos cabeçalhos, não na documentação.

Quando você passa do limite

Você recebe uma resposta HTTP 429 Too Many Requests.

Cabeçalhos da resposta:

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

Corpo da resposta:

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

O que fazer:

1. Leia o Retry-After. Esse número (neste exemplo, 24) é o tempo de espera, em segundos, até o seu bucket recarregar o suficiente para aceitar a próxima requisição.
2. Espere pelo menos esse tempo antes de tentar de novo. Clientes HTTP comuns (axios, requests do Python, Postman etc.) respeitam o Retry-After automaticamente quando configurados para tentar de novo após um 429.
3. Não tente de novo antes do que o Retry-After indica. Isso só gera mais erros 429 e aciona os alertas de violações repetidas descritos abaixo.

Violações repetidas

Passar do limite uma ou duas vezes é normal, por exemplo, quando um script inicia e aquece o cache. Mas se a sua integração continuar ultrapassando o limite, tomamos providências:

Se a sua chave for desativada, corrija a causa (normalmente um loop descontrolado no seu script) e fale com o suporte para reativá-la. O contador zera uma hora depois da sua última violação.

Observações por integração

API REST direta

O bucket padrão de 60 requisições/minuto. Os endpoints ficam em https://vistasocial.com/api/*; veja a referência completa em apidocs.vistasocial.com. Autentique com a sua chave de API no cabeçalho x-api-key. Não é preciso indicar a integração.

Zapier / Make / n8n

Cada plataforma funciona no seu próprio bucket. Envie o cabeçalho api_client nas suas requisições personalizadas para sabermos de qual integração vem a chamada: api_client: zapier, api_client: make ou api_client: n8n. (No n8n você também pode enviar User-Agent: n8n, que também reconhecemos.) Sem uma dessas indicações, a requisição cai no bucket da API REST direta e divide o orçamento com as suas próprias chamadas à API.

(Se você usa os nossos apps prontos do Zapier / Make / n8n, isso já é feito automaticamente.)

MCP (ChatGPT, Claude, Cursor etc.)

As integrações MCP têm dois limites que se somam:

• Limite por minuto (este artigo): 180 requisições/minuto no canal mcp. É maior que o padrão de 60/min das outras integrações, porque assistentes de IA costumam enviar requisições em rajadas e nem sempre respeitam o ritmo do limite padrão.
• Limite de rajada por ferramenta (dentro do MCP): cada ferramenta também tem o seu próprio limite de rajada de curto prazo. Ferramentas custosas como generateImage e generateVideo têm um limite menor (por exemplo, 10 de rajada / 5 por minuto para generateImage); ferramentas leves usam um padrão generoso. Quando uma ferramenta ultrapassa o próprio limite, o assistente de IA recebe um erro estruturado de "rate limited" na resposta e é instruído a esperar antes de tentar de novo.

Você não precisa configurar nada para nenhum dos dois: ambos se aplicam automaticamente. O limite por ferramenta aparece principalmente com assistentes que tentam gerar grandes lotes de mídia em uma única conversa; o uso normal e variado de ferramentas raramente chega nele.

Apps OAuth

O tráfego autenticado via OAuth usa tokens bearer em vez de chaves de API, mas vale o mesmo orçamento de 60 requisições/minuto, restrito ao espaço de trabalho que concedeu a autorização.

Perguntas frequentes

"Estou bem abaixo de 60 requisições por minuto, por que recebo erros 429?"

Confira estes pontos:

1. Outras integrações usam a mesma chave de API? Se vários scripts usam a mesma chave, eles dividem o bucket. Sempre que possível, use uma chave de API separada para cada integração.
2. Você está enviando o api_client? Um zap do Zapier e um script personalizado que usam a mesma chave de API sem o cabeçalho api_client caem no mesmo bucket direct. Envie o cabeçalho pelo Zapier para separá-los.
3. Rajadas no começo do minuto? A janela reinicia no começo de cada ciclo de "primeira requisição", e não na virada do minuto do relógio. Distribua as requisições de forma uniforme ao longo do minuto em vez de enviá-las todas no primeiro segundo.

"Vocês podem aumentar o meu limite?"

Para espaços de trabalho em um plano pago do Vista Social, sim: fale com o seu account manager ou abra um ticket e vamos avaliar. Espaços de trabalho gratuitos não podem ter o limite aumentado, mas podem assinar a qualquer momento.

"Operações em massa contam como uma requisição ou várias?"

Uma requisição HTTP = uma contagem, não importa quantos dados ela leve. Um POST /publishing/posts que agenda em 10 perfis conta como 1 requisição, não 10.

"Requisições GET contam no mesmo bucket que POST / PUT?"

Sim, o limite é por requisição, não por tipo de operação. Leitura e escrita dividem o mesmo orçamento de 60 requisições/minuto em cada integração.

"Onde vejo o meu uso atual do limite?"

Nos cabeçalhos de resposta de cada chamada à API. Hoje não temos um painel para isso; os cabeçalhos são a fonte oficial.

"E se o meu cliente de API não aceitar o Retry-After automaticamente?"

Basta ler o Retry-After da resposta 429 e chamar sleep(N) (ou equivalente) antes de tentar de novo. Todo cliente HTTP permite isso; só não é automático em todos.

Ainda com problemas?

Fale com o suporte do Vista Social e envie:

• O nome do seu espaço de trabalho ou o ID da entidade raiz
• A integração que está sendo limitada (zapier, mcp etc.)
• Um exemplo do corpo de uma resposta 429 (para verificarmos qual bucket está envolvido)
• O horário do 429 mais recente

A partir daí, investigamos.