GUIA

Rate Limits

Sistema de token bucket para controle de uso da Storefront API.

Visão Geral

A Storefront API usa um sistema de token bucket para controlar o uso. Cada hostname (loja) possui um bucket de tokens que é consumido a cada request. Tokens são repostos continuamente.

Configuração do Bucket

Parâmetro	Valor	Descrição
Capacidade	1.000 tokens	Máximo de tokens no bucket (permite bursts).
Reposição	1.000 tokens/min	Taxa de reposição contínua.
Janela	60 segundos	Intervalo completo de reposição.

Custo por Operação

Cada request consome tokens proporcionalmente à sua complexidade:

Tipo de Operação	Custo	Descrição
Query simples (< 5 campos)	1 token	Queries leves como buscar dados da loja.
Query média (5-14 campos)	3 tokens	Queries com múltiplos campos aninhados.
Query complexa (15+ campos)	5 tokens	Queries pesadas com muitos relacionamentos.
Mutation	10 tokens	Operações de escrita (login, carrinho, checkout).
Introspection	50 tokens	Queries `__schema` e `__type`.

Dica: Para otimizar o consumo de tokens, solicite apenas os campos que você precisa. Uma query pedindo 3 campos custa 1 token, enquanto a mesma query com 20 campos custa 5 tokens.

Headers de Resposta

Toda resposta da API inclui headers com o estado do bucket:

Header	Descrição
X-RateLimit-Limit	Capacidade total do bucket (1000).
X-RateLimit-Remaining	Tokens restantes no bucket.
X-RateLimit-Cost	Tokens consumidos por esta request.
Retry-After	Segundos até ter tokens suficientes (apenas em 429).
X-RateLimit-Reset	Timestamp ISO de quando tokens estarão disponíveis (apenas em 429).

Resposta de Limite Excedido

Quando o bucket é esvaziado, a API retorna HTTP 429 com detalhes sobre quando tentar novamente.

Comportamento do Bucket

O token bucket permite bursts de requests seguidos por períodos de baixa atividade. Se a loja não fizer requests por 1 minuto, o bucket volta à capacidade máxima de 1000 tokens.

Isso significa que uma loja pode, por exemplo:

Fazer 1000 queries simples em sequência rápida (burst)
Ou 100 mutations em sequência rápida
Após esgotar, aguardar a reposição contínua (~16 tokens/segundo)

Limites por Mutation

Além do token bucket global, mutations sensíveis possuem rate limits adicionais por IP:

Mutation	Limite	Janela
clientLogin / login	10 requests	1 minuto
addShoppingCartItem	50 requests	1 minuto
officeAddNewOrder	10 requests	5 minutos
getFileDirectUploadLink	10 requests	1 minuto

Headers Normais

HTTP

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Cost: 3

Resposta 429

HTTP

HTTP/1.1 429 Too Many Requests
Retry-After: 5
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-11T18:45:30.000Z

Body da Resposta 429

JSON

{
  "errors": [{
    "message": "Storefront API rate limit exceeded. Try again in 5 seconds.",
    "extensions": {
      "code": "STOREFRONT_RATE_LIMIT_EXCEEDED",
      "retryAfterSeconds": 5,
      "cost": 10,
      "remaining": 0
    }
  }]
}

Monitorar Tokens no Cliente

JavaScript

const response = await fetch('/graphql', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query, variables })
});

const remaining = response.headers.get('X-RateLimit-Remaining');
const cost = response.headers.get('X-RateLimit-Cost');

console.log(`Tokens: ${remaining} remaining (cost: ${cost})`);