GUIA

Rate Limits

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

Visão Geral

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

Configuração do Bucket

ParâmetroValorDescrição
Capacidade500 tokensMáximo de tokens no bucket (permite bursts).
Reposição500 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 um produto.
Query média (5-14 campos)3 tokensQueries com múltiplos campos.
Query complexa (15+ campos)5 tokensQueries com muitos relacionamentos.
Mutation (insert/update)10 tokensCriar ou atualizar produto.
Mutation (delete)10 tokensRemover produto.
Mutation com imagens20 tokensMutations que incluem upload de imagens base64.
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 (500).
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 o token não fizer requests por 1 minuto, o bucket volta à capacidade máxima de 500 tokens.

Isso significa que você pode, por exemplo:

  • Fazer 500 queries simples em sequência rápida (burst)
  • Ou 50 mutations em sequência rápida
  • Ou 25 mutations com imagens em sequência rápida
  • Após esgotar, aguardar a reposição contínua (~8 tokens/segundo)

Limites Adicionais

RecursoLimiteDescrição
Tamanho do body2 MBTamanho máximo do payload por request.
Profundidade de query7 níveisProfundidade máxima de aninhamento.
Imagens por request10Máximo de imagens base64 por mutation.

Operações em Massa

Para importação ou sincronização de grandes catálogos, monitore os tokens restantes:

Headers Normais

HTTP
HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 490
X-RateLimit-Cost: 10

Resposta 429

HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 8
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-13T15:30:00.000Z

Body da Resposta 429

JSON
{
  "errors": [{
    "message": "Office API rate limit exceeded. Try again in 8 seconds.",
    "extensions": {
      "code": "OFFICE_RATE_LIMIT_EXCEEDED",
      "retryAfterSeconds": 8,
      "cost": 10,
      "remaining": 0
    }
  }]
}

Batch com Rate Limit

JavaScript
async function batchImport(items, processFn) {
  const results = [];

  for (const item of items) {
    const response = await processFn(item);
    const remaining = response.headers
      .get('X-RateLimit-Remaining');

    results.push(response);

    if (Number(remaining) < 10) {
      const retryAfter = response.headers
        .get('Retry-After') || '5';
      await new Promise(r =>
        setTimeout(r, Number(retryAfter) * 1000)
      );
    }
  }

  return results;
}