Rate limits

Limite por chave#

O limite vale por chave, não por loja nem por IP. Respostas que passam pelo limite trazem quanto dele já foi usado:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 42

• X-RateLimit-Limit: requisições permitidas na janela de 1 minuto.
• X-RateLimit-Remaining: requisições que ainda cabem na janela atual.
• X-RateLimit-Reset: segundos até a janela recomeçar.

Quando o limite estoura#

A requisição que passar do limite recebe 429, com type igual a rate_limit_error e code igual a rate_limited. A resposta traz o header Retry-After com os segundos de espera.

HTTP/1.1 429 Too Many Requests
Retry-After: 18

Falhas de autenticação#

Há também um limite por IP só para falhas de autenticação: até 10 respostas 401 por minuto. Depois disso, cada nova falha desse IP recebe 429 com rate_limited e Retry-After, em vez de 401.

Esse limite conta só falhas. Uma chave válida nunca é bloqueada por ele, mesmo vinda de um IP que já passou do limite. Requisições que deram certo, ou que falharam por outro motivo (como 403 ou 400), não contam.

Boas práticas#

• Use limit=100 ao listar pedidos para fazer menos requisições.
• Prefira GET /v1/orders/summary a percorrer todos os pedidos só para contar.
• Se vários processos usam a mesma chave, eles dividem o mesmo limite. Distribua as chamadas ou crie uma chave por sistema.