Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt

Use this file to discover all available pages before exploring further.

Rate Limits

A Engine API aplica limites de taxa para garantir estabilidade e performance para todos os parceiros. Os limites são aplicados por API Key.

Limites por plano

PlanoRequests/minutoRequests/horaEmissões/mês
Starter601.000500
Professional1005.0005.000
Enterprise30015.000Ilimitado
Limites de emissão são contados por documento fiscal autorizado (NFe, NFCe, CTe, MDFe, NFSe). Consultas e downloads não contam para esse limite.

Headers de rate limit

Toda resposta da API inclui headers que indicam seu consumo atual:
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1714200000
HeaderDescrição
X-RateLimit-LimitTotal de requests permitidos no período
X-RateLimit-RemainingRequests restantes no período atual
X-RateLimit-ResetTimestamp Unix de quando o contador reseta

Resposta 429 (Too Many Requests)

Quando o limite é atingido, a API retorna:
{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "error": "Too Many Requests"
}
Com o header adicional:
Retry-After: 45

Retry com backoff exponencial

Implemente retry automático para lidar com rate limits de forma elegante:
import { EngineApiClient, EngineApiError } from '@engineapi/sdk';

async function emitirComRetry(
  client: EngineApiClient,
  params: any,
  maxRetries = 3
) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await client.nfe.emitir(params);
    } catch (error) {
      if (error instanceof EngineApiError && error.isRateLimited) {
        if (attempt === maxRetries) throw error;

        const waitMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        console.log(`Rate limited. Retry em ${waitMs}ms...`);
        await new Promise(r => setTimeout(r, waitMs));
      } else {
        throw error; // Não é rate limit, propaga o erro
      }
    }
  }
}

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 NFe autorizada não muda. Cache o resultado de GET /v1/nfe/:id para evitar chamadas repetidas.

Endpoints isentos

Alguns endpoints não contam para o rate limit:
EndpointMotivo
GET /healthHealth check de monitoramento
GET /v1/nfe/statusStatus do SEFAZ
GET /v1/nfe/pdf/:keyDownload de PDF (cache CDN)
GET /v1/nfe/xml/:keyDownload de XML (cache CDN)

Precisa de mais?

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