Limites

Taxa de requisições

Cada cliente de servidor (cliente de integração) tem seu próprio limite: uma taxa sustentada em requisições por segundo e uma rajada que cabe acima dela. O limitador é um balde de tokens por cliente, compartilhado por todas as instâncias da API: o balde comporta até a rajada, é reabastecido na taxa sustentada, e cada requisição autenticada consome um token. Um pico de logins às 9h é absorvido pela rajada; um fluxo constante acima da taxa sustentada, não.

Nível	Sustentada	Rajada	Quando
Padrão	5 por segundo	10	Usado por padrão em toda nova aplicação e todo novo cliente de servidor
10	10 por segundo	20	Por solicitação no console, aprovada na hora e aplicada automaticamente
Legado	1 por segundo	1	Aplicações configuradas antes de 07/10/2026, até que uma mudança seja solicitada

O console mostra o limite em vigor para cada cliente de servidor em Integração e saúde → Limite de requisições. O limite pertence ao cliente de servidor, não à credencial: rotacionar o segredo mantém o limite, e mudar o limite mantém o key_id e o segredo.

Acima do limite: 429

Exceder a taxa resulta em 429 rate-limited com Retry-After em segundos inteiros (hoje sempre 1). A requisição foi autenticada e o request_id dela já foi consumido, então repeti-la é uma nova tentativa: mesmo corpo, request_id novo, timestamp atual e assinatura nova (veja idempotência e nova tentativa). Reutilizar o request_id antigo resulta em 401 request-replayed.

Toda tentativa autenticada, inclusive as respondidas com 429, também consome um orçamento de segurança que é o dobro do nível (10 por segundo com rajada de 20 no nível padrão). Respeitando o Retry-After, ele nunca é atingido. Um cliente que continua fazendo novas tentativas sem esperar o esgota, e a credencial fica então bloqueada por pelo menos 10 minutos, durante os quais toda requisição é recusada com 401. Ao receber 429, faça backoff; não faça novas tentativas em um laço apertado.

Uma saturação momentânea do serviço aparece como 503 assessment-unavailable, também com Retry-After; repita da mesma forma, como uma nova tentativa.

Cabeçalhos de um 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 1
X-Correlation-Id: <opaque, for support>

429 · corpo

{
  "type": "https://fingertrackid.dev/problems/rate-limited",
  "title": "Limite de assessments atingido",
  "status": 429,
  "correlation_id": "corr-problem-rate-limit-0001",
  "retryable": true
}

Pedir uma taxa maior

No console, abra Integração e saúde → Limite de requisições, escolha o cliente de servidor e clique em Pedir aumento de limite. Um membro com o papel Administrador da empresa ou Gestor de integração pode pedir. O que acontece em seguida:

1. Aprovação: a solicitação é aprovada assim que é enviada, sempre, inclusive na primeira vez que um nível é usado na aplicação. Ninguém precisa revisá-la.
2. Aplicação: a plataforma aplica o novo limite automaticamente em instantes, mesmo enquanto esse cliente continua enviando avaliações; nada muda na sua integração (mesmo identificador de chave e mesmo segredo). Uma solicitação só aumenta o limite, então as requisições já em andamento continuam válidas sob o limite maior.

O console oferece até 10 por segundo. Para mais de 10 por segundo, fale com o suporte em contato@fingertrackid.com informando o nome da aplicação e o identificador do cliente de servidor. Um novo cliente de servidor criado no console recebe o nível atual da aplicação.

Sessões do Web SDK

O SDK do navegador tem seus próprios limites por aplicação, separados da taxa de requisições do cliente de servidor:

Limite	Valor
Novas sessões do SDK	5 por segundo, rajada de 20
Sessões do SDK vigentes ao mesmo tempo	Até 1000 por aplicação
Duração de uma sessão do SDK	30 minutos, nunca estendida
Coletas por sessão do SDK	1; o SDK 0.2.0 e posteriores abrem uma nova sessão para cada nova coleta, no máximo uma por segundo por cliente
Requisições de coleta e de contexto do evento por sessão do SDK	Uma a cada 250 ms, o que o SDK respeita sozinho
Contextos do evento por sessão do SDK	128
Evidência do navegador e contexto do evento	Por aplicação: 60 segundos para aplicações provisionadas antes da introdução da janela de 300 segundos (outubro de 2026), 300 segundos para as provisionadas desde então, a partir de quando a coleta chega ao FingerTrackID (a janela de evidência)
Cabeçalhos da requisição	Exatamente os que o SDK envia; qualquer cabeçalho adicionado por instrumentação da página faz o preflight de CORS falhar (cabeçalhos de rastreamento)

Uma sessão recusada faz collect() retornar status: 'UNAVAILABLE'; a avaliação continua sendo enviada com event_context_token: null. Os detalhes estão em coleta e contexto do evento, e os prazos das próprias requisições do SDK em tempo e latência.

Outros limites

Limite	Valor	Observação
Janela do timestamp da assinatura	±300 s	401 timestamp-out-of-window
Janela de occurred_at para uma nova operação	±300 s	400 occurred-at-out-of-window
Retenção do request_id	Pelo menos 601 s	Nunca reutilize um, nem depois da janela
Corpo da requisição	16384 bytes	413 payload-too-large
Corpo da resposta	65536 bytes	Nunca é maior; acima disso, trate a resposta como indeterminada
event_context_token	4096 caracteres	400

Nenhum desses números é uma cota comercial nem uma garantia de vazão, e o deadline_ms das jornadas não é um SLA.