Limites

Esta página é para quem agenda a integração: quantas chamadas cabem por minuto e quanto dado cabe em cada chamada. Os números abaixo foram medidos numa chamada real à API.

Chamadas por minutoCopiar link da seção

Planeje a integração para 30 chamadas por minuto. A API roda em mais de uma instância, e cada instância conta as chamadas que recebeu. Por isso a 31ª chamada pode passar, e o 429 pode vir um pouco depois. Em 28/09/2026, 100 chamadas seguidas à mesma rota em staging tiveram 90 respostas 200 e 10 respostas 429. Não conte com essa folga: ela depende de quantas instâncias estão no ar.

O limite conta cada rota em separado. Com a mesma chave, 30 chamadas a /api/v1/chart-of-accounts não impedem uma chamada a /api/v1/companies no mesmo minuto.

O 429 traz o cabeçalho Retry-After com os segundos que faltam para liberar:

HTTP/1.1 429 Too Many Requests
Retry-After: 56

{"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."}

Espere esse tempo e repita a chamada.

As respostas de sucesso trazem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Eles mostram um limite geral de 600 chamadas por minuto, e não o de 30 por rota. Não use esses cabeçalhos para medir o limite de 30; conte as chamadas do seu lado ou trate o 429.

PaginaçãoCopiar link da seção

As rotas de leitura (GET) devolvem uma página por vez:

{
  "data": [{ "id": 35, "razaoSocial": "Sonda Staging Ltda" }],
  "pagination": { "page": 1, "limit": 50, "total": 2, "pages": 1 }
}

pagination.total é o total de linhas e pagination.pages o total de páginas. Para ler tudo, peça page=1, page=2 e assim por diante até pagination.pages. Uma página depois da última responde 200 com data vazio.

async function lerTudo(rota) {
  const linhas = [];
  for (let page = 1; ; page++) {
    const r = await fetch(
      `${process.env.TOPO_API}${rota}${rota.includes('?') ? '&' : '?'}limit=100&page=${page}`,
      {
        headers: { Authorization: `Bearer ${process.env.TOPO_CHAVE}` },
      },
    );
    if (r.status === 429) {
      await new Promise((ok) => setTimeout(ok, Number(r.headers.get('retry-after') ?? 60) * 1000));
      page--;
      continue;
    }
    const corpo = await r.json();
    linhas.push(...corpo.data);
    if (page >= corpo.pagination.pages) return linhas;
  }
}

A leitura não é uma fotografia: se um balancete for importado no meio dela, as páginas seguintes já refletem a importação. Para um relatório fechado, leia uma competência de cada vez, com period.

Tamanho de cada chamadaCopiar link da seção

Um balancete real costuma ter algumas centenas de linhas, bem abaixo do limite. Acima de 20.000 linhas a chamada responde 400 com a mensagem lineItems aceita no máximo 20000 linhas por chamada.

Exemplo: uma rotina do ERPCopiar link da seção

Um ERP que envia o balancete de 40 empresas no fechamento faz 40 chamadas à mesma rota. Com o limite de 30 por minuto, espace as chamadas em pelo menos 2 segundos, ou envie em dois lotes com um minuto entre eles. Se vier um 429, espere o Retry-After e continue de onde parou.

Um relatório de BI que lê 5.000 conciliações faz 50 chamadas à mesma rota com limit=100 (100 com o padrão de 50). Use sempre limit=100 e espace a leitura para caber em 30 chamadas por minuto.