Referência
Limites de taxa
Os limites protegem a API contra enxurradas, não contra revendedores normais. Cada conta tem um limite por minuto que cresce com o gasto, e alguns limites estreitos cobrem as ações pesadas. Regras próprias de um pedido, como a espera da reposição, retornam o próprio código de erro em vez de um 429.
Camadas de limitação
Por IP
20.000 pedidos / minuto / endereço IP
Aplicado antes da validação da chave, de modo que a enumeração de chaves por força bruta seja limitada. Compartilhado entre todas as chaves atrás do mesmo IP. O padrão é definido globalmente e não é configurável pelo usuário.
Janela partilhada da conta
120–2.400 pedidos / 60 segundos móveis
Todas as chaves API ativas de uma conta consomem o mesmo contador. A escala fixa de gasto bem-sucedido vitalício fornece o limite, salvo se existir uma substituição direta de RPM.
Específico por ação
Depende da ação
Services, catalog, cancel, refill e as ações de webhook têm seus próprios limites estreitos, mostrados abaixo. Eles se somam ao limite da conta; não o substituem.
Limites por ação
Esses limites contam por conta por minuto. Um 429 de algum deles informa action em X-RateLimit-DeniedBy. Cancel e refill contam IDs de pedido, não requisições, então uma chamada para 10 pedidos usa 10 dos IDs que você tem por minuto. Um cancel ou refill com mais IDs do que isso, até 100, é aceito quando é a sua primeira chamada do minuto e usa o minuto inteiro.
| Ação | Por minuto | O que é contado |
|---|---|---|
| services | 10 | Requisições |
| catalog | 30 | Requisições |
| cancel | 30 | IDs de pedido |
| refill | 30 | IDs de pedido |
| webhook.* | 10 | Requisições |
Escala de gasto bem-sucedido vitalício
O limite da sua conta acompanha o seu gasto bem-sucedido acumulado ao longo da vida; um nível mais alto libera de imediato um limite maior. O teto por IP de 20.000 requisições por minuto vale antes de a chave ser verificada. Um administrador pode definir um limite direto para uma conta, de até 10.000. O nível da sua conta está no cabeçalho X-RateLimit-Tier e na sua página de API.
| Nível | Gasto vitalício mínimo | Pedidos / minuto |
|---|---|---|
| 0 | $ 0 | 120 |
| 1 | $ 10 | 300 |
| 2 | $ 50 | 600 |
| 3 | $ 100 | 900 |
| 4 | $ 500 | 1.200 |
| 5 | $ 1.000 | 1.800 |
| 6 | $ 2.500 | 2.400 |
Cabeçalhos de resposta
Cabeçalhos de resposta
X-RateLimit-Limit- Em respostas normais, o limite efetivo de pedidos por minuto partilhado pela conta. Num 429, o limite informado pela camada que rejeitou.
X-RateLimit-Remaining- Em respostas normais, os pedidos restantes na janela partilhada da conta. Num 429, o valor restante informado pela camada que rejeitou.
X-RateLimit-Reset- Número relativo de segundos até a janela informada reiniciar; não é um timestamp Unix.
X-RateLimit-Tier- O nível ganho pelo gasto bem-sucedido vitalício (0–6). Uma substituição personalizada de RPM não altera este valor.
X-RateLimit-DeniedBy- Enviado em respostas 429 quando um limitador identificado rejeita a chamada: "ip", "api_requests_per_minute" ou "action".
Retry-After- Em uma resposta 429 ou 503 que pode ser repetida, aguarde pelo menos os segundos indicados por Retry-After antes de tentar novamente. Para action=add, reutilize a mesma chave de idempotência após aguardar.
Como lidar com respostas 429
Aguarde o Retry-After quando ele estiver presente.
Caso contrário, aguarde os segundos de X-RateLimit-Reset. Os dois valores são atrasos relativos, não horários de relógio; adicione variação aleatória antes de tentar de novo.Leia X-RateLimit-DeniedBy.
Ele indica o limite que recusou a chamada. Trocar de chave não ajuda, porque os limites de conta, IP e ação são compartilhados.Use webhooks em vez de consultar repetidamente.
Os webhooks chegam pelo menos uma vez, então deixe seu tratador idempotente e useaction=statuspara conferir o que for importante.Agrupe quando puder.
Status, cancel e refill aceitam até 100 IDs em uma requisição; a contagem de IDs de pedido continua valendo para cancel e refill.