Rate limits
A API Externa aceita até 100 requisições por minuto por empresa, somando todas as rotas. O limite é da empresa inteira: todos os sistemas que usam a mesma chave dividem a mesma cota, inclusive em chamadas simultâneas.
Mesmo assim, não dependa desse número na sua integração. Trate a resposta 429 como descrito abaixo e espalhe as chamadas ao longo do tempo (por exemplo, sincronizações em lote de madrugada e com paginação).
Cabeçalhos de resposta
As respostas trazem o consumo do limite geral da conta:
| Cabeçalho | Descrição |
|---|---|
X-RateLimit-Limit | Limite da janela |
X-RateLimit-Remaining | Requisições restantes na janela |
X-RateLimit-Reset | Quando a janela renova |
Retry-After | Só na resposta 429 do limite geral: segundos até poder tentar de novo |
Toda resposta traz também X-Request-ID, o identificador da requisição. Informe-o ao suporte quando abrir um chamado.
Ao passar do limite (429)
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"status": 429,
"timestamp": "2026-11-17T14:30:00.000Z",
"path": "/external/v1/persons",
"errors": [],
"friendlyMessage": "Limite de requisições excedido. Tente novamente em 23 segundos."
}
No limite por rota, o tempo de espera vem na própria friendlyMessage. Quando houver Retry-After, prefira o valor dele.
Tentando de novo
Use espera exponencial com variação aleatória:
tentativa 1: 1 s + 0 a 500 ms
tentativa 2: 2 s + 0 a 500 ms
tentativa 3: 4 s + 0 a 500 ms
tentativa 4: 8 s + 0 a 500 ms
tentativa 5: 16 s + 0 a 500 ms
JavaScript:
async function comRetentativa(fn, maxTentativas = 5) {
for (let tentativa = 0; tentativa < maxTentativas; tentativa++) {
const resposta = await fn()
if (resposta.status !== 429 || tentativa === maxTentativas - 1) return resposta
const retryAfter = Number(resposta.headers.get('retry-after'))
const base = retryAfter > 0 ? retryAfter * 1000 : 2 ** tentativa * 1000
await new Promise((r) => setTimeout(r, base + Math.random() * 500))
}
}
Python:
import random
import time
import requests
def com_retentativa(method, url, max_tentativas=5, **kwargs):
for tentativa in range(max_tentativas):
resposta = requests.request(method, url, **kwargs)
if resposta.status_code != 429 or tentativa == max_tentativas - 1:
return resposta
retry_after = resposta.headers.get("Retry-After")
base = int(retry_after) if retry_after else 2 ** tentativa
time.sleep(base + random.uniform(0, 0.5))
Para consumir menos
- Guarde em cache as leituras que mudam pouco (categorias, contas, centros de custo).
- Filtre com
relationse peça só o que precisa (veja Paginação e filtros). - Use webhooks em vez de consultar de tempos em tempos para saber o que mudou.
- Espalhe as chamadas no tempo em vez de mandar rajadas.
A nossa equipe ajuda você a configurar e usar esse recurso.