Skip to main content

​
Visão geral

A caBRAPI aplica limites de requisição (rate limit) para garantir estabilidade, segurança e desempenho da plataforma para todos os clientes.
  • Os limites são aplicados por plano contratado e medidos em janela fixa de 1 minuto.
  • Cada rota possui um contador independente — o consumo de um endpoint não afeta o limite dos demais.
  • O consumo é contado por credencial de API (sua apiKey) — cada integração mede o próprio uso.

​
Limites por plano

Básico

Até 60 requisições por minuto.

Profissional

Até 120 requisições por minuto.

Hyper

Até 1.600 requisições por minuto.
Caso o limite seja ultrapassado, novas requisições são temporariamente bloqueadas, retornando erro 429 até que a janela seja reiniciada.

​
Headers de controle

Toda resposta inclui headers que permitem acompanhar o consumo em tempo real: Quando o limite é atingido, a resposta de erro também inclui:

​
Quando o limite é excedido

Ao ultrapassar o limite, a API responde 429 Too Many Requests e recusa novas requisições até a janela reiniciar:
A resposta usa o mesmo envelope status/code dos demais erros da API. Veja Erros.
O tempo de espera é informado no header Retry-After (em segundos), não no corpo da resposta.

​
Boas práticas

  • Monitore o header X-RateLimit-Remaining para se autorregular antes de atingir o limite.
  • Ao receber um 429, respeite o Retry-After e só tente novamente após o tempo indicado.
  • Implemente retentativa com backoff exponencial para lidar com picos de tráfego.
  • Evite polling agressivo: consulte dados em intervalos maiores ou use webhooks para receber eventos em tempo real.
Se o seu fluxo demanda mais requisições, avalie o upgrade de plano — o upgrade eleva o limite imediatamente.

​
Paginação

Nos endpoints de listagem, use os parâmetros page e limit para controlar o volume de dados por resposta.
  • page: inteiro maior ou igual a 1
  • limit: inteiro entre 1 e 100
Quando esses parâmetros forem inválidos, a API retorna:
  • 400 INVALID_PAGINATION_LIMIT
  • 400 INVALID_PAGINATION_PAGE

​
Paginação por cursor

Em listas grandes (mais de ~100 itens), prefira a paginação por cursor, que mantém a performance em qualquer volume de dados:
  • Faça a primeira chamada sem cursor e use o campo nextCursor da resposta.
  • Envie o nextCursor como cursor na próxima requisição para avançar na lista.
  • O fim da lista é indicado por nextCursor: null + hasMore: false (a API responde 200 com array vazio).
  • No modo offset, as respostas também incluem nextCursor/hasMore, permitindo migrar para cursor sem recomeçar do zero.
Os limites podem ser ajustados conforme novos planos ou condições específicas da caBRAPI. Sempre consulte a documentação atualizada para garantir informações corretas.