Limitação
Quantos registros vêm por página, quantas requisições cabem por segundo e como reagir quando a API pede calma.
A API limita o tamanho da página; a velocidade depende da sua infraestrutura. Respeitar a paginação evita leituras incompletas e 429 de proxy.
Tamanho da página
| Parâmetro | Padrão | Máximo |
|---|---|---|
per_page |
20 registros | 20 registros |
Valores acima de 20 são reduzidos para 20: a API usa o teto e continua paginando. Para volumes grandes, pagine seguindo links.next em vez de tentar aumentar a página.
Velocidade das chamadas
A API não aplica limite de requisições por token hoje. Você pode chamar livremente, desde que respeite a paginação. Se a sua infraestrutura (proxy, CDN ou gateway) impuser um limite, a resposta será 429 Too Many Requests — trate como no exemplo abaixo.
{
"message": "Too Many Requests"
}
Como reagir ao 429
- Pare de enviar por alguns instantes.
- Repita a chamada com espera crescente (1 s, 2 s, 4 s, 8 s…).
- Se persistir, reduza a concorrência do seu processo.
async function chamarComBackoff(fn, tentativas = 5) {
for (let i = 0; i < tentativas; i++) {
const resposta = await fn();
if (resposta.status !== 429) return resposta;
const espera = Math.min(1000 * 2 ** i, 15000);
await new Promise((r) => setTimeout(r, espera));
}
throw new Error('Limite de requisições persistente');
}
429 e consome seu limite. O backoff exponencial resolve o caso na maioria das vezes.Recomendações para integrações grandes
| Cenário | Recomendação |
|---|---|
| Catálogo com milhares de produtos | Processar em lotes com pausa entre eles |
| Pedidos do dia | Usar webhook em vez de polling |
| Reenvio após falha | Reprocessar somente o que falhou, não o lote inteiro |
| Muitas atualizações de estoque | Agrupar por produto e evitar chamadas redundantes |
| Horário de pico de vendas | Priorizar consulta de pedidos; adiar sincronização de catálogo |
Quanto tempo leva uma sincronização
Como referência: 1.000 produtos com 4 fotos cada ficam em torno de 5.000 chamadas; só para listar 1.000 produtos com per_page=20 são ~50 páginas. Processe em lotes e prefira janelas fora do horário de pico para não sobrecarregar o seu ambiente.