Limites de requisições

Cotas por minuto e diárias da API e do servidor MCP do SociaHive, além dos cabeçalhos e da estratégia de espera.

O SociaHive aplica limites de requisições por usuário em cada chave de API e token OAuth. Os limites são divididos pelo tipo de operação, não pelo método HTTP: uma ferramenta que faz uma única leitura gasta menos da cota do que uma que entrega o grafo de um fluxo gerado.

As quatro faixas

Faixa	Limite	Janela	Exemplos
read	120 requisições	1 minuto	`list_flows`, `get_flow`, `list_scheduled_posts`, `get_analytics_overview`, qualquer chamada que busca sem alterar
write	30 requisições	1 minuto	`create_flow`, `update_node`, `add_edge`, `create_scheduled_post`, `cancel_scheduled_post`
expensive	5 requisições	1 minuto	`generate_flow` (geração de fluxo com IA), `search_published_media` (busca vetorial), qualquer chamada que aciona um modelo de linguagem ou um armazenamento vetorial
daily	1.000 requisições	24 horas	Um teto que vale para todas as faixas somadas: protege contra loops descontrolados

Todos os limites são por usuário (quem tem a chave de API ou o sujeito do OAuth), não por chave. Criar várias chaves não multiplica a sua cota.

Resposta quando você passa de uma faixa

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
  }
}

O cabeçalho Retry-After é a referência: respeite-o. O details.window indica qual faixa estourou, caso você queira reduzir o ritmo só dessa classe de operação.

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')
}

Não tente de novo antes do que o Retry-After indica: você só vai bater na mesma faixa outra vez e gastar a cota do teto diário.

Limites específicos do MCP

Além das quatro faixas acima, o transporte HTTP do MCP adiciona um teto de 200 sessões simultâneas. Uma “sessão” é uma conexão SSE aberta; as ociosas expiram em 5 minutos. Se você abre muitos clientes MCP de vida curta em paralelo (por exemplo, em jobs de CI), feche a sessão de forma explícita ao fim de cada lote em vez de esperar a coleta de lixo (garbage collection).

O teto diário é o limite que você realmente vai atingir

Para a maioria dos usos, as faixas por minuto são generosas: 120 leituras por minuto é mais do que qualquer sessão interativa usa. O teto diário de 1.000 requisições é o primeiro que scripts de importação em massa e tarefas agendadas agressivas atingem.

Se você faz trabalho em massa, prefira os endpoints em lote (posts.bulk, bulk_update_flows) a loops de chamadas isoladas: uma chamada em lote conta como uma requisição na sua cota, não importa quantas entidades ela toque.

O que NÃO tem limite de requisições

Os endpoints de autenticação (/api/oauth/*): limitados à parte pela Cloudflare, na borda
As páginas públicas do site e o /api/v1/openapi.json (estático, somente leitura)
Os webhooks de saída: têm limites e regras próprios; veja o guia de webhooks

Limites por plano

As faixas acima são as mesmas em todos os planos pagos. O que muda por plano são os limites de recursos (contas conectadas, posts agendados por mês, créditos de IA etc.), não a taxa de requisições da API. Os limites de recursos do plano são devolvidos pela ferramenta whoami do MCP e pelo endpoint REST /api/v1/usage.