Limites, planos e cotas

Rate limit

Três limites se somam, do mais amplo ao mais estreito. Uma chamada precisa passar por todos.

O teto por tenant é o do seu plano, e não está listado aqui de propósito: ele vive no banco de dados, muda sem que esta página saiba, e a relação atual está na página de planos do painel (/billing). Quando o tenant não tem plano associado, vale o default RATE_LIMIT_API_MAX (60/min).

Os baldes são independentes: um envio consome do balde de envio e do balde do tenant. Na prática, quem barra primeiro é o mais estreito dos três.

Se a chave de API não for reconhecida (inexistente, errada, revogada ou vencida), os baldes passam a ser contados por IP: você não ganha cota extra mandando chave inválida.

Ao estourar qualquer um deles, a resposta é 429:

{
  "error": true,
  "code": "RATE_LIMITED",
  "message": "Muitas requisições. Tente novamente em 59s.",
  "retryAfter": 59
}

O retryAfter vem em segundos, e vale respeitá-lo: insistir antes disso mantém você no limite. Os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset acompanham as respostas e permitem antecipar o bloqueio.

Um detalhe que importa se você roda atrás de NAT ou em contêineres: na /api/v1, com a chave reconhecida, os três limites seguem a sua conta, e não o IP. Todos os seus processos dividem a mesma cota, saiam de onde saírem, e outra conta que sai pelo mesmo IP não gasta a sua. Sem chave reconhecida, o limite global é por IP.

Limites do WhatsApp

Independentes dos nossos, e mais consequentes: o WhatsApp tem mecanismos próprios de detecção de abuso, e disparos em massa podem levar ao banimento do número. Nenhuma configuração da nossa API protege contra isso.

Na prática: espace os envios, evite mandar a mesma mensagem para muitos números em sequência, e prefira números que já tenham histórico de conversa. Um número banido não volta.

Recursos que dependem do plano

Três endpoints exigem uma funcionalidade específica:

Sem ela, a resposta é 403 com o nome da funcionalidade em feature:

{
  "success": false,
  "error": {
    "code": "PLAN_FEATURE_NOT_ALLOWED",
    "feature": "message_queue",
    "planCode": "basic"
  }
}

O assistente de IA (servidor MCP) também depende do plano: a consulta exige mcp, e o envio, a fila e as etiquetas pelo assistente exigem mcp_escrita. Além dos limites desta página, o envio pelo assistente tem um teto de 200 por dia por conta. Detalhes em Assistentes de IA.

Por que este guia não traz uma tabela de plano × recurso: essa configuração vive no banco de dados e já foi ajustada mais de uma vez. Uma tabela aqui envelheceria em silêncio, exatamente o problema que esta documentação existe para evitar. A relação atual está na página de planos do painel (/billing).

Cota de instâncias

Criar instância consome cota. Ao estourar, POST /instances devolve 403.

Para saber onde você está antes de tentar, use GET /api/v1/status, que traz a contagem atual:

{ "instances": { "total": 3, "connected": 2 } }

O campo connected conta as que estão realmente conectadas ao WhatsApp neste momento, instâncias criadas mas nunca pareadas contam em total e continuam ocupando cota. Se você bateu no limite sem entender por quê, procure instâncias órfãs e remova-as com DELETE /instances/{id}.

Assinatura

Sem assinatura ativa (ou período de avaliação em curso), toda a API v1 devolve 403, inclusive envio e consulta nas instâncias que já existem. A exceção é GET /status, que continua respondendo para você descobrir o motivo do bloqueio.

Se a verificação do plano falhar por instabilidade do nosso lado, a resposta é 503 com o código PLAN_CHECK_UNAVAILABLE. Esse não é um bloqueio: tente de novo em instantes.

Instalações em modo cliente único

Numa instalação dedicada a um único cliente, não há cobrança nem planos, e todos os gates acima são desligados. Os 403 de plano simplesmente não acontecem, e todos os recursos ficam disponíveis. Os limites de rate limit continuam valendo.

Guia verificado em 05/08/2026 contra a API v1.

← Todos os guias