---
title: "Limites de requisição"
description: "Limites da API do Emissor de Nota: 120 requisições por minuto por chave e 100.000 por mês, cabeçalhos X-RateLimit, resposta 429 e como repetir com espera."
url: https://docs.emissordenota.com/limites
language: pt-BR
---
# 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

| Limite | Valor | Como é contado |
| --- | --- | --- |
| Por minuto | 120 requisições | Por chave de API, em janelas de 60 segundos. |
| Por mês | 100.000 requisições | 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**

```http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1794231780
```

| Cabeçalho | Significado |
| --- | --- |
| 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
HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 120
X-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**

```javascript
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.
