Pular para o conteúdo principal

Limites e cota

Valores​

LimiteValor padrãoVale para
Por chave60 requisições por minutocada chave de API
Por organização120 requisições por minutotodas as chaves da organização somadas
Cota mensal50.000 requisições por mêsa organização
Por endereço IP300 requisições por minutoqualquer requisição, antes de conferir a chave
Itens por página50 (padrão), até 100listas
Tamanho do corpo256 KBPOST e PATCH

Os valores em vigor para a sua organização aparecem no painel e na rota /v1/me. Se precisar de limites maiores, fale com o suporte.

A cota mensal​

  • A cota renova no dia 1º de cada mês, às 00:00 UTC (21:00 do último dia do mês, no horário de Brasília).
  • A cota não usada não passa para o mês seguinte.
  • O dono e os administradores recebem um e-mail quando a organização usa 80% e 100% da cota.

O que conta na cota​

Cada requisição autenticada que chega a ser processada conta 1, seja leitura ou escrita, inclusive as que terminam em erro por dados inválidos ou falta de escopo (403 insufficient_scope, 404, 409, 412, 422) e as respostas 304.

Não contam:

  • requisições recusadas por limite ou cota (429);
  • requisições sem chave válida (401);
  • requisições recusadas por falta de acesso, de assinatura ou de aceite dos termos (402 e os 403 de acesso: api_access_not_enabled, api_access_suspended, workspace_not_eligible, terms_not_accepted);
  • falhas do Validades (5xx).

Cabeçalhos de limite​

Toda resposta autenticada informa a situação dos limites:

CabeçalhoSignificado
RateLimit-Limitrequisições permitidas por minuto para a chave
RateLimit-Remainingrequisições restantes no minuto atual
RateLimit-Resetsegundos até o limite por minuto renovar
X-Quota-Limitcota mensal da organização
X-Quota-Remainingrequisições restantes no mês
X-Quota-Resetquando a cota renova (ISO 8601)

Erro 429​

codeQuando
rate_limitedlimite por minuto da chave, da organização ou do IP
quota_exceededcota mensal esgotada

A resposta traz o cabeçalho Retry-After com os segundos de espera. Respeite esse valor antes de tentar de novo.

HTTP/1.1 429 Too Many Requests
Retry-After: 18
Content-Type: application/json; charset=utf-8

{
"error": {
"code": "rate_limited",
"internal_code": 106,
"message": "Rate limit of 60 requests per minute for this API key exceeded. Try again in 18s.",
"request_id": "req_01JC…"
}
}

Boas práticas​

  • Respeite o Retry-After e, para outras falhas temporárias (5xx, rede), tente de novo com intervalos crescentes (por exemplo 1 s, 2 s, 4 s, 8 s), com um limite de tentativas.
  • Busque só o que mudou com updated_since e /v1/deletions, em vez de baixar tudo de novo a cada vez. Veja Paginação e sincronização.
  • Use limit=100 nas listas para gastar menos requisições.
  • Use include=batches em GET /v1/products/{id} para trazer o produto e os lotes em uma requisição só.
  • Use If-None-Match ao consultar um item que você já tem: se nada mudou, a resposta é um 304 sem corpo.
  • Espalhe tarefas agendadas pelo minuto, em vez de disparar tudo no segundo zero.