Limites de requisições

A Certivant aplica um limite de requisições da API por minuto para proteger a plataforma contra clientes descontrolados e vizinhos barulhentos. Fique abaixo do limite e você nunca verá throttling; ultrapassá-lo resulta em um 429 com cabeçalhos que informam exatamente quando tentar novamente.

O limite

O seu teto por minuto é definido pelo seu plano. O operador da plataforma também pode conceder um limite personalizado por cliente, que é sempre limitado ao teto do plano. O número efetivo é o que o cabeçalho X-RateLimit-Limit informa em cada resposta — leia-o em vez de fixar um valor no código.

Limites padrão por plano

Estes são os valores padrão — o operador da plataforma pode ajustar o teto por plano e conceder à sua organização um limite personalizado mais alto (até o teto do plano). Você pode ver o limite efetivo da sua organização, somente para leitura, no painel em KYC → Desenvolvedor.

Se você precisar de um teto mais alto para o tráfego de produção, peça ao seu contato de conta (ou, em implantações self-hosted, ao operador da plataforma) para elevar o teto do seu plano ou o seu limite personalizado.

Cabeçalhos de resposta (em toda resposta autenticada)

Toda resposta de sucesso inclui o estado atual do limite de requisições:

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
Content-Type: application/json

{ "data": [...], "pagination": {...} }

Leia esses cabeçalhos no seu cliente para desacelerar de forma proativa — não espere por um 429 se você já vê X-RateLimit-Remaining: 3.

A resposta 429

Ao ultrapassar o limite, a próxima requisição retorna:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Max 120 requests per 60s. Retry in 18s."
  }
}

X-RateLimit-Reset informa exatamente quanto tempo esperar. Use-o em vez de adivinhar.

Estratégia de novas tentativas

O manipulador correto mais simples:

async function withRateLimit<T>(fn: () => Promise<Response>): Promise<T> {
  while (true) {
    const res = await fn();
    if (res.status !== 429) {
      if (!res.ok) throw await readError(res);
      return res.json() as Promise<T>;
    }
    const retryAfterSec = Number(res.headers.get("X-RateLimit-Reset") ?? 60);
    await sleep(retryAfterSec * 1000 + 100); // pad by 100ms for clock skew
  }
}

Três propriedades a manter:

1. Respeite o X-RateLimit-Reset. Um intervalo menor apenas bate no limite de novo.
2. Adicione cerca de 100 ms de folga para compensar a diferença de relógio entre a sua máquina e a borda da Certivant.
3. Limite suas tentativas se a requisição não for crítica. Insistir por 5 minutos em uma listagem não urgente desperdiça recursos dos dois lados.

Como projetar para respeitar o limite

A maior economia vem de usar webhooks. A principal causa de chamados de suporte do tipo "estou atingindo o limite de requisições" são integrações que fazem polling para detectar mudanças de estado — não faça isso; configure webhooks no lugar.

Comportamento em rajadas

O limite é aplicado como uma janela fixa: a primeira requisição inicia um contador de 60 segundos, e cada requisição conta contra o seu teto até que a janela seja reiniciada. Distribua o tráfego contínuo de forma uniforme, em vez de disparar todo o orçamento do minuto nos primeiros segundos.

Se você tiver um padrão de rajada conhecido (por exemplo, um job em lote diário que processa 500 registros), espace as chamadas:

for (const record of records) {
  await processOne(record);
  await sleep(500); // 2 req/s — comfortably under typical ceilings
}

O que acontece quando o Redis está inacessível

Se a instância do Redis usada para os limites de requisições estiver temporariamente inacessível, a Certivant falha aberta — ela não bloqueia o seu tráfego. Você verá respostas 2xx normais, sem os cabeçalhos X-RateLimit-*. Quando o Redis voltar, a aplicação normal do limite será retomada. Isso significa que uma falha do Redis do nosso lado não interrompe a sua integração.

A entrega de webhooks é separada

O limite de requisições se aplica às suas chamadas de saída para a Certivant. As entregas de webhook de entrada, da Certivant para o seu endpoint, não consomem nenhuma cota. Não existe um "limite de webhooks" com o qual você precise se preocupar.

Endpoints públicos

Os endpoints que não exigem chave de API (GET /api/status, GET /api/kyc/public/status, os endpoints de envio de formulário) têm um limite de requisições por IP separado, de 60 requisições por minuto. Esse limite se aplica ao endereço IP de quem chama, e não a uma chave de API. Ele é definido de forma conservadora porque esses endpoints são acessíveis sem autenticação; se a sua interface voltada ao solicitante estiver atingindo esse limite, direcione as chamadas pelo seu próprio backend, para que compartilhem um IP sob o seu controle.