Pular para o conteúdo principal

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çalhoDescrição
X-RateLimit-LimitLimite da janela
X-RateLimit-RemainingRequisições restantes na janela
X-RateLimit-ResetQuando a janela renova
Retry-AfterSó 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 relations e 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.
Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.