Limites de Requisições

🔍 Preview

Os limites de requisições se aplicam exclusivamente à API Privada e existem para proteger a plataforma contra loops excessivos, normalmente causados por erros de código ou falhas de integração.

Eles não têm como objetivo limitar uso legítimo, mas sim evitar impactos de performance e instabilidade provocados por chamadas repetitivas não intencionais.

---

🎯 Quando os limites são aplicados?

Os limites de requisições:

• ✅ Afetam apenas a API Privada
• ❌ Não se aplicam ao front-end da loja, checkout ou Store Theme
• São acionados principalmente em cenários como: loops infinitos, retries sem controle, erros de tratamento de resposta
ℹ️ Informação

Se sua integração está corretamente implementada, é raro atingir o limite.

🧠 Como os limites funcionam

• Cada endpoint possui um limite próprio
• O limite geralmente é calculado por minuto
• Ao atingir o limite, novas requisições são temporariamente bloqueadas
ℹ️ Informação

Após o tempo de espera, o acesso ao endpoint é automaticamente liberado.

⚠️ Erro retornado ao atingir o limite

Quando o limite de requisições é excedido, a API retorna o erro 429 — Too Many Requests.

📦 Exemplo de response

1{
2  "status": false,
3  "data": {
4    "code": 429,
5    "errorCode": "THROTTLE_LIMIT_REACHED",
6    "message": "Try again in 21 seconds."
7  }
8}

Esse erro indica que:

• O limite foi atingido
• O endpoint foi temporariamente bloqueado
• É necessário aguardar antes de tentar novamente

👀 Cabeçalhos de resposta (Rate Limit)

Além do body, a API retorna headers informativos, que ajudam a controlar novas tentativas:

1X-RateLimit-Limit: 30
2X-RateLimit-Reset: 21

🔎 O que cada header significa

• X-RateLimit-Limit: quantidade máxima de requisições permitidas para o recurso no intervalo definido.
• X-RateLimit-Reset: tempo restante (em segundos) para que o limite seja resetado e novas requisições possam ser feitas.
ℹ️ Informação

Esses headers devem ser usados para controle inteligente de chamadas.

🛠️ Boas práticas

• Implementar retry com backoff exponencial
• Nunca faça retry imediato após erro 429
• Valide condições de erro antes de repetir a chamada
• Monitore logs e métricas da integração
⚠️ Atenção

Retries agressivos sem controle tendem a agravar o problema, não resolver.

🔗 Limites ≠ restrição de uso

É importante reforçar:

• Limites não são cotas de uso
• Não representam cobrança adicional
• Não afetam integrações bem implementadas
• Existem apenas como mecanismo de segurança

🏁 Próximo passo

Os limites de requisição se aplicam exclusivamente à API Privada, sendo relevantes principalmente para integrações e ferramentas externas. Agora, siga o caminho que faz mais sentido para o seu cenário:

🎨 Trabalhando no front-end da loja

Se o seu objetivo é customizar a experiência da loja, os limites de requisição não impactam o desenvolvimento de temas.

Store Theme: estrutura da loja e experiência do cliente Checkout: fluxo de compra, carrinho e finalização Area Restrita: dados do cliente e experiência pós-compra

🔐 Criando integrações ou ferramentas externas

Se você está desenvolvendo integrações, automações ou ERPs, é importante entender como autenticar corretamente e consumir a API Privada de forma segura.

API Privada: autenticação, endpoints e boas práticas