Limites de requisições

Para proteger as lojas de abuso e de força bruta, a API limita quantas requisições um mesmo endereço IP pode fazer por minuto em cada grupo de rotas. Passou do limite, a resposta é 429 Too Many Requests até o balde encher de novo.

Os limites

O limite funciona como um balde de fichas: o balde comporta o número de requisições da coluna "Capacidade" e se reenche continuamente na proporção da capacidade por minuto. Ou seja, dá para fazer uma rajada do tamanho do balde e depois uma requisição a cada 60 / capacidade segundos.

Detalhes que mudam o cálculo:

• O IP é o do cliente real. A plataforma lê a cadeia de proxies pela direita e só acredita nela quando a conexão vem de um proxy dela. Enviar um X-Forwarded-For próprio não muda o seu balde.
• Cada grupo tem um balde só. Todas as rotas /api/v1/admin/... dividem os mesmos 1.200. O login tem o balde dele, separado do restante de /api/v1/auth/.
• Vários usuários atrás do mesmo IP somam. Um escritório ou uma NAT de nuvem conta como um cliente só.
• Algumas rotas têm limite próprio, além do global. A rota pública de localização de loja aceita 20 requisições por minuto por IP; as chaves de API da vitrine (sfk_...) têm o limite configurado em cada chave (padrão 100 por minuto, resposta 429 rate_limit_exceeded).

A resposta 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{"error":"rate limit exceeded","detail":"too many requests, please try again later"}

Retry-After: 60 é um valor conservador fixo; na prática uma ficha volta mais cedo (veja a coluna da tabela). Esperar 60 segundos sempre funciona.

Como reagir

# Retry-After vem no cabeçalho da resposta
curl -s -D - -o /dev/null -X POST "$BASE_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@minhaloja.com.br","password":"SENHA"}' | grep -i "^HTTP\|retry-after"

Como ficar abaixo do limite

• Guarde o token em vez de logar a cada chamada. Renove com o refresh (Tokens e escopos).
• Use per_page=100 nas listas, em vez de muitas páginas pequenas.
• Distribua a carga. Uma sincronização que faz milhares de chamadas deve espaçá-las (por exemplo, 10 por segundo na API de administrador) em vez de disparar tudo de uma vez.
• Integração de seller: o limite do seller é bem menor.
• Cuidado com a validação por tecla. As checagens de e-mail, CPF e CNPJ no cadastro dividem o balde de 10 por minuto das rotas de autenticação. Valide quando o campo perde o foco, não a cada tecla.

Erros comuns

• Repetir o login em laço apertado. Com 5 por minuto, o balde esvazia na 6ª tentativa e todos os usuários do mesmo IP ficam bloqueados.
• Ignorar o 429 e continuar mandando. Cada requisição negada ainda conta contra você; respeite o Retry-After.
• Esperar um limite por usuário. Dois usuários no mesmo IP dividem o balde.
• Assumir que o GraphQL também tem esses limites. Ele não passa por esta tabela. O GraphQL é descrito em Plataforma e integrações.

Veja também