Limite de Requisições (Rate Limit)

Para manter a plataforma estável para todos, as requisições à API da Triction são
limitadas por um rate limit. Toda resposta informa, em cabeçalhos, o seu limite atual e
quanto ainda resta — basta lê-los para se adaptar automaticamente.

O que está sujeito ao limite

O rate limit vale para as chamadas autenticadas por token de API (cabeçalho
Authorization: Bearer <token>), tanto da API principal quanto da API de Revendedores
(/wlapi/). O uso pela interface web (usuários logados no CRM) não é afetado por este limite.

Como a contagem funciona

A contagem é por conta — todos os usuários e tokens de uma mesma conta compartilham o
mesmo limite. (Cada subconta de um revendedor tem o seu próprio limite, separado.)
As requisições são contadas dentro de uma janela de tempo fixa. Quando a janela termina,
o contador zera. Use o cabeçalho X-Rate-Limit-Reset para saber exatamente quantos
segundos faltam para isso.

Cabeçalhos de resposta

Toda resposta da API traz três cabeçalhos:

Cabeçalho	Significado
`X-Rate-Limit`	Total de requisições permitidas na janela atual.
`X-Rate-Limit-Remaining`	Quantas requisições ainda restam antes de atingir o limite.
`X-Rate-Limit-Reset`	Segundos restantes até o contador zerar.

Sempre confie nos cabeçalhos, e não em valores fixos no seu código: o limite pode mudar
ao longo do tempo (veja abaixo) e os cabeçalhos sempre refletem o valor vigente.

Qual é o seu limite

O limite de cada conta acompanha o número de usuários ativos: quanto maior a equipe, maior
a folga de requisições. A regra é 12 requisições por usuário ativo por janela, com um piso
equivalente a 5 usuários (ou seja, no mínimo 60).

Usuários ativos	Limite por janela
até 5	60
10	120
20	240
50	600

O limite é recalculado automaticamente quando usuários são criados, ativados ou
desativados, além de uma verificação periódica. Por isso ele pode variar — e por isso vale
sempre ler o cabeçalho X-Rate-Limit.

Contas podem ter um limite personalizado definido pela Triction. Nesse caso, o valor
configurado prevalece e também aparece em X-Rate-Limit.

Quando o limite é atingido

Se você ultrapassar o limite dentro da janela, a API responde com HTTP 429 e a mensagem:

Quantidade de requisições máxima atingida no intervalo de tempo determinado.

Os mesmos cabeçalhos (X-Rate-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset)
acompanham a resposta 429, então você sabe quanto esperar antes de tentar de novo.

Boas práticas

Leia X-Rate-Limit-Remaining e desacelere conforme ele se aproxima de zero.
Ao receber 429, aguarde o tempo indicado em X-Rate-Limit-Reset antes de repetir
(idealmente com exponential backoff).
Espalhe o trabalho ao longo do tempo em vez de disparar muitas chamadas em rajada.
Prefira operações em lote e evite polling agressivo — para receber eventos em tempo
real, use os Eventos de Webhook.