Limites de uso
A API de integração aplica um limite de requisições por token, para proteger a plataforma contra loops e abuso. O limite é generoso: o uso normal de um ERP, hub ou automação não encosta nele.
O limite
| Chamadas | Limite | Janela | Conta por |
|---|---|---|---|
| Rotas autenticadas pelo token de integração | 300 | 1 minuto | token (sk_live_*) |
POST /api/integration/auth (emitir token) | 5 | 1 minuto | ver Autenticação |
O limite de 300/min vale para todas as rotas que você chama com o bearer token de integração (produtos, pedidos, estoque, etc.), somadas. A contagem é por token: cada credencial tem seu próprio balde, então separar sistemas em credenciais distintas também separa os limites.
Emitir o token (
/integration/auth) tem um limite próprio, mais estrito, porque é a porta de entrada — detalhes em Autenticação. Algumas rotas pontuais também podem ter um limite próprio; nesses casos vale o menor.
Headers
Toda resposta de uma rota de integração traz o estado do seu balde:
| Header | Significado |
|---|---|
X-RateLimit-Limit | Teto da janela (ex.: 300). |
X-RateLimit-Remaining | Quantas chamadas ainda cabem na janela atual. |
Use o Remaining para se auto-regular: se estiver baixo, espace as chamadas antes de bater no teto.
Quando você estoura: 429
Passou do teto, a API responde 429 Too Many Requests com o envelope padrão:
{
"success": false,
"code": 429,
"message_code": "TOO_MANY_REQUESTS",
"description": "Muitas requisições em pouco tempo. Aguarde antes de tentar novamente."
}Junto vem o header Retry-After, com os segundos que faltam para a janela reabrir. O tratamento correto:
- Leia o
Retry-After. - Espere esse tempo — tentar antes não adianta, só renova o bloqueio.
- Tente a chamada de novo.
Boas práticas
- Respeite o
Retry-After. Reenviar antes do prazo só consome tentativas e mantém você bloqueado. - Não faça polling agressivo. Para acompanhar jobs assíncronos (DANFE, etiquetas), 3–10s entre chamadas basta.
- Cache o token. Não chame
/integration/autha cada requisição — ele tem o limite mais estrito (5/min). Emita um token e reutilize pelos 30 dias (ver Autenticação). - Uma credencial por sistema. Além de organizar, isola o limite: um sistema em loop não derruba os outros.
- Trate 429 como sinal de espera, não de falha. Faça backoff e siga.