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:
X-RateLimit-Limit: 120X-RateLimit-Remaining: 87X-RateLimit-Reset: 1794231780CabeçalhoSignificado
- X-RateLimit-LimitO máximo de requisições por janela.
- X-RateLimit-RemainingQuantas requisições ainda cabem na janela atual.
- X-RateLimit-ResetO momento em que a janela recomeça, em segundos desde 01/01/1970.
- Retry-AfterSó 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.
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.
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.