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âmetroValorDescrição
Capacidade1.000 tokensMáximo de tokens no bucket (permite bursts).
Reposição1.000 tokens/minTaxa de reposição contínua.
Janela60 segundosIntervalo completo de reposição.

Custo por Operação

Cada request consome tokens proporcionalmente à sua complexidade:

Tipo de OperaçãoCustoDescrição
Query simples (< 5 campos)1 tokenQueries leves como buscar dados da loja.
Query média (5-14 campos)3 tokensQueries com múltiplos campos aninhados.
Query complexa (15+ campos)5 tokensQueries pesadas com muitos relacionamentos.
Mutation10 tokensOperações de escrita (login, carrinho, checkout).
Introspection50 tokensQueries __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:

HeaderDescrição
X-RateLimit-LimitCapacidade total do bucket (1000).
X-RateLimit-RemainingTokens restantes no bucket.
X-RateLimit-CostTokens consumidos por esta request.
Retry-AfterSegundos até ter tokens suficientes (apenas em 429).
X-RateLimit-ResetTimestamp 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:

MutationLimiteJanela
clientLogin / login10 requests1 minuto
addShoppingCartItem50 requests1 minuto
officeAddNewOrder10 requests5 minutos
getFileDirectUploadLink10 requests1 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})`);