engineAPIengine·API
Começar

Rate Limits

Limites de uso da Engine API: headers, limites por plano, tratamento de 429 e retry com backoff.

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

| Plano | Requests/minuto | Requests/hora | Emissões/mês | |-------|----------------|---------------|-------------| | Dev | 5 | 100 | Sandbox ilimitado | | Starter | 60 | 1.000 | 500 | | Growth | 300 | 5.000 | 3.000 | | Scale | 600 | 15.000 | 10.000 | | Enterprise | Ilimitado | Ilimitado | Ilimitado |

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
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1714200000

| Header | Descrição | |--------|-----------| | X-RateLimit-Limit | Total de requests permitidos no período | | X-RateLimit-Remaining | Requests restantes no período atual | | X-RateLimit-Reset | Timestamp Unix de quando o contador reseta |

Resposta 429 (Too Many Requests)

Quando o limite é atingido, a API retorna:

json
{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "error": "Too Many Requests"
}

Com o header adicional:

http
Retry-After: 45

Retry com backoff exponencial

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

typescript
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

Endpoints isentos

Alguns endpoints não contam para o rate limit:

| Endpoint | Motivo | |----------|--------| | GET /health | Health check de monitoramento | | GET /v1/nfe/status | Status do SEFAZ | | GET /v1/nfe/pdf/:key | Download de PDF (cache CDN) | | GET /v1/nfe/xml/:key | Download de XML (cache CDN) |

Precisa de mais?

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