Rate Limits

Visão Geral

Esta página registra as cotas das APIs descritas abaixo, aplicadas pelo Rack::Attack em produção. Os valores exibidos são os padrões definidos no código e podem ser alterados pelo operador nas variáveis indicadas. Quando mais de uma regra corresponde à requisição, vale a primeira cota atingida. Ao exceder uma cota, a API retorna 429 Too Many Requests.

A coluna Configuração distingue regras fixas das configuráveis e informa o padrão usado pelo código. Este inventário garante somente as regras implementadas no backend atual; cotas apenas planejadas ou descritas fora dele não fazem parte do contrato.

Em desenvolvimento e teste, esse middleware fica desabilitado. Portanto, valide limites no ambiente de produção ou em um ambiente iniciado explicitamente como produção, sem usar uma carga que afete usuários reais.

Resposta 429

O contrato atual não adiciona headers X-RateLimit-Limit, X-RateLimit-Remaining ou X-RateLimit-Reset. A opção do Rack::Attack que adicionaria Retry-After também está desabilitada. Não dependa desses headers para controlar retentativas.

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain

Retry later

Global e Autenticação

Além das regras específicas, toda requisição conta para o limite global por IP. Não existe uma cota geral por token, inbox ou app. Login com MFA não consome as regras de login comum: usa as duas regras MFA, por IP e por token.

RACK_ATTACK_ALLOWED_IPS acrescenta IPs à safelist; localhost já é permitido. A rota /health também é isenta. Em produção, ENABLE_RACK_ATTACK=false desliga todas as regras.

Widget

Estas três regras existem somente quando ENABLE_RACK_ATTACK_WIDGET_API é true, que é o padrão. O limite global continua valendo em paralelo.

APIs Autenticadas

Regras por conta extraem account_id da rota. As regras por usuário de relatórios e meta usam uid quando presente e, caso contrário, api_access_token; sem um desses identificadores, a requisição não entra nessa cota por usuário, mas continua sujeita às demais regras correspondentes.

Automações e Webhooks

As credenciais dos webhooks são convertidas em SHA-256 antes de compor a chave armazenada. O webhook de automação de pipeline aceita o token no path, query ou body JSON; sem token, essa regra específica não cria uma chave, embora o limite global por IP continue ativo.

Módulo de Atendimentos — Limites por Canal

O módulo de Atendimentos está disponível em todas as licenças. O widget anônimo depende da habilitação operacional do agendamento público na conta; as APIs autenticadas não são bloqueadas por plano nem possuem uma regra própria por token ou por conta — recebem apenas as cotas gerais ou outras regras que também correspondam à rota.

Tratando Erro 429

Quando receber um erro 429, use backoff exponencial para retentar a requisição:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) {
      return response;
    }

    // O backend atual não envia Retry-After; mantenha o fallback.
    const retryAfter = response.headers.get("Retry-After");
    const delay = retryAfter
      ? parseInt(retryAfter) * 1000
      : Math.pow(2, attempt) * 1000;

    console.log(`Rate limited. Aguardando ${delay}ms...`);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw new Error("Max retries exceeded");
}

Boas Práticas

• Controle localmente a taxa de chamadas; a resposta não informa quantas requisições restam
• Use backoff exponencial com jitter aleatório para retries
• Agrupe operações somente quando o endpoint oferecer uma operação em lote
• Implemente cache local para dados que não mudam frequentemente
• Use webhooks em vez de polling para receber atualizações em tempo real
• Não presuma que o valor padrão é o valor implantado: o operador pode sobrescrever as cotas configuráveis