Skip to main content
A engineAPI aplica limites de taxa para garantir estabilidade e performance para todos os parceiros. Os limites são aplicados por partner: todas as suas chaves compartilham o mesmo orçamento.

Limites por plano

A janela do rate limit é sempre de 1 segundo. Não existe limite por minuto, hora ou dia. O limite é aplicado por partnerId (não por IP) e vale para toda requisição autenticada, emissão, consulta ou download.

Headers de rate limit

Toda resposta da API inclui headers que indicam seu consumo atual:

Resposta 429 (Too Many Requests)

Quando o limite é atingido, a API retorna o mesmo envelope RFC 7807 usado em todos os erros (ver Erros e Rejeições):
Com o header adicional:
Retry-After é sempre 1 {/* fact:rateLimit.retryAfterSeconds */} (a janela do rate limit é de 1 segundo). Não é um valor dinâmico calculado a partir do consumo.

Retry com backoff exponencial

Implemente retry automático para lidar com rate limits de forma elegante:

Boas práticas

Verifique X-RateLimit-Remaining em cada resposta. Se estiver abaixo de 10%, reduza a velocidade das chamadas proativamente.
Se precisa emitir muitas notas de uma vez, use uma fila (Bull, RabbitMQ, SQS) com intervalo entre emissões ao invés de chamadas paralelas.
Consultas (GET) e downloads (PDF/XML) são mais leves que emissões (POST). Se possível, faça consultas em horários de menor movimento.
O status de uma NF-e autorizada não muda. Cache o resultado de GET /v1/nfe/:id para evitar chamadas repetidas.

Endpoints sem autenticação

Nenhum endpoint é isento de rate limit. O que muda é a régua aplicada:
Os endpoints públicos de monitoramento vivem fora do prefixo /v1 (/health, /health/live, /version) e não consomem o limite do seu plano: usam um limite global por IP. Use GET /health à vontade para health check de infraestrutura.

Precisa de mais?

Se o seu volume ultrapassa os limites do plano Scale, entre em contato para um plano Enterprise personalizado: