Limites de taxa

Chastify limita a taxa de tráfego da API de extensão para proteger sessões de bloqueio, armazenamento, dispositivos e sistemas de notificação.

Os limites de taxa se aplicam tanto ao tráfego de ponte iframe roteado por meio de Chastify quanto às chamadas de backend feitas com chaves de API de desenvolvedor.

Baldes de extensão atuais

Balde	Limite	Pontos finais típicos
Leitura	300/min	session.get, state.get, metadata.get, leituras de arquivos, status de ação regular
Escrever	120/min	Gravações de estado do backend, atualizações de metadados, configuração de ações regulares, criação de execuções verificadas pelo servidor
Carregar	10/min	Carregamento de arquivos de tempo de execução e de instalação
Ação	30/min	Ações de bloqueio, comandos de dispositivo, registros personalizados, notificações personalizadas, liquidação de resultados verificada pelo servidor
Token	30/min	Geração de token de inicialização/autenticação de sessão iframe

Os limites são avaliados em um intervalo de um minuto.

observação

Essas são as configurações padrão da plataforma. Administradores/proprietários do site Chastify podem configurar substituições por extensão para extensões oficiais ou com volume de requisições excepcionalmente alto. As substituições são armazenadas na configuração do aplicativo da extensão e mantidas em cache brevemente no Redis para uma rápida pesquisa do caminho da requisição.

informação

Os buckets de upload e ação são intencionalmente mais restritos do que os buckets de leitura/estado. Os uploads consomem armazenamento e largura de banda. As ações podem afetar o estado de bloqueio, dispositivos, notificações e o histórico visível ao usuário.

Como as chaves são contadas

As chaves de limitação de taxa incluem:

• ID de usuário autenticado Chastify quando a interface de usuário de terceiros chama um endpoint
• ID da chave da API do desenvolvedor quando seu backend chama os endpoints da sessão da extensão.
• Endereço IP para caminhos anônimos ou não autenticados
• o alvo sessionId ou lockId quando disponível

Isso significa que uma única sessão de extensão com alto volume de dados não deve consumir todo o orçamento global da API de extensões.

Comportamento recomendado do cliente

Seu iframe ou backend deve tratar 429 Too Many Requests como uma condição normal que permite novas tentativas.

Use o mecanismo de recuo exponencial para falhas repetidas:

async function callWithBackoff<T>(fn: () => Promise<T>, attempts = 4): Promise<T> {
  let delayMs = 500;

  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      return await fn();
    } catch (error: any) {
      const status = error?.status ?? error?.response?.status;
      if (status !== 429 || attempt === attempts) throw error;

      await new Promise((resolve) => setTimeout(resolve, delayMs));
      delayMs *= 2;
    }
  }

  throw new Error("request_failed");
}

Orientações para a Ponte Iframe

Para clientes de ponte iframe:

• Armazene em cache os resultados session.get durante toda a vida útil da página, a menos que precise de novos dados de bloqueio.
• Armazene localmente as alterações temporárias da interface do usuário e envie as alterações confiáveis ​​para o seu servidor.
• Evite loops de polling rápidos. Prefira leituras acionadas pelo usuário ou intervalos de atualização lentos.

Exemplo de salvamento no backend com debounce:

let saveTimer: number | undefined;

function scheduleStateSave(data: Record<string, unknown>) {
  window.clearTimeout(saveTimer);
  saveTimer = window.setTimeout(() => {
    fetch("/your-extension-backend/state", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    }).catch(console.error);
  }, 500);
}

Orientações para extensão de backend

Para chamadas de backend com uma chave de API de desenvolvedor:

• Mantenha as ações privilegiadas verificadas pelo servidor e acionadas pelo usuário.
• Utilize PUT/PATCH /api/extensions/sessions/:sessionId/state somente no seu painel administrativo com credenciais da API de desenvolvedor.
• Não tente novamente realizar ações de bloqueio às cegas se a primeira tentativa tiver sido bem-sucedida.
• Torne o acordo do jogo/desafio idempotente com um ID de execução.
• Carregar arquivos somente quando o usuário os enviar explicitamente.
• Armazene seus próprios registros externos caso precise de telemetria de alta frequência.

aviso

Nunca aumente os limites de ação para compensar chamadas de navegador não verificadas. O código iframe do navegador não é confiável. Mutações sensíveis devem ser validadas pelo seu backend antes de chamar Chastify.

Qual balde devo esperar?

Exemplos comuns:

• GET /api/extensions/sessions/:sessionId usa o bucket de leitura.
• GET /api/extensions/sessions/:sessionId/state usa o bucket de leitura.
• PUT/PATCH /api/extensions/sessions/:sessionId/state usa o bucket de escrita.
• POST /api/extensions/sessions/:sessionId/files usa o bucket de upload.
• POST /api/extensions/sessions/:sessionId/action usa o bucket de ação.
• POST /api/extensions/sessions/:sessionId/device-command usa o bucket de ação.
• POST /api/extensions/sessions/:sessionId/logs/custom usa o bucket de ação.
• POST /api/extensions/sessions/:sessionId/notifications/custom usa o bucket de ação.
• GET /api/extensions/sessions/:sessionId/auth usa o bucket de tokens.

Baldes granulares futuros

Os buckets atuais são amplos. Chastify pode subdividi-los ainda mais à medida que a API do desenvolvedor crescer, por exemplo:

• state.write
• metadata.write
• lock.action
• notifications.custom
• device.command
• files.upload

Os limites por extensão podem ser aumentados pelos administradores/proprietários do site Chastify quando uma extensão oficial ou aprovada de alto volume tiver uma necessidade legítima. Projete os clientes de forma que o tratamento de 429 seja genérico e não dependa de nomes de bucket exatos ou padrões fixos da plataforma.