ConceitosLimites de requisição

Limites de requisição

A API limita quantas chamadas cada chave faz por minuto e quantas o escritório faz por mês. Toda resposta informa quanto ainda resta, para o seu sistema se ajustar antes de bater no limite.

Os limites

  • Por minuto
    Valor
    120 requisições
    Como é contado
    Por chave de API, em janelas de 60 segundos.
  • Por mês
    Valor
    100.000 requisições
    Como é contado
    Por escritório, somando todas as chaves de produção. A contagem recomeça no dia 1º.

O sandbox tem o mesmo limite por minuto e não consome a franquia mensal. Consulte os limites aplicáveis em Configurações › API e integrações.

Cabeçalhos de controle

Toda resposta traz a situação da janela atual:

Cabeçalhos da resposta
X-RateLimit-Limit: 120X-RateLimit-Remaining: 87X-RateLimit-Reset: 1794231780

CabeçalhoSignificado

  • X-RateLimit-Limit
    O máximo de requisições por janela.
  • X-RateLimit-Remaining
    Quantas requisições ainda cabem na janela atual.
  • X-RateLimit-Reset
    O momento em que a janela recomeça, em segundos desde 01/01/1970.
  • Retry-After
    Só nas respostas 429. Quantos segundos esperar antes de tentar de novo.

Quando o limite é excedido

A API responde 429 e não processa a chamada. Nada é emitido nem alterado, então repetir depois da espera é seguro.

Resposta · 429 Too Many Requests
HTTP/1.1 429 Too Many RequestsRetry-After: 18X-RateLimit-Limit: 120X-RateLimit-Remaining: 0{  "erro": {    "codigo": "limite_excedido",    "mensagem": "Limite de 120 requisições por minuto atingido.",    "requisicao_id": "req_7Hc2Lq9Vx1"  }}

Quando a franquia do mês acaba, o código é franquia_esgotada e o Retry-After aponta para a virada do mês.

Repetindo com espera

Ao receber 429, espere o tempo de Retry-After. Em respostas 5xx e falhas de rede, repita com espera crescente e uma pequena variação aleatória, para as tentativas não chegarem todas juntas.

Node.js
async function chamar(url, opcoes, tentativa = 0) {  const resposta = await fetch(url, opcoes);  if (resposta.status !== 429 && resposta.status < 500) return resposta;  if (tentativa === 5) throw new Error("Sem resposta depois de 5 tentativas");  const espera = Number(resposta.headers.get("Retry-After"))    || Math.min(2 ** tentativa, 30) + Math.random();  await new Promise((ok) => setTimeout(ok, espera * 1000));  return chamar(url, opcoes, tentativa + 1);}

Como gastar menos requisições

  • Use webhooks em vez de consultar o status da nota em laço.
  • Liste com filtros de empresa, período e status em vez de consultar item a item.
  • Guarde em cache o que muda pouco, como empresas, clientes e serviços.
  • Em rotinas de lote, limite as chamadas em paralelo e distribua o envio ao longo do minuto.