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âmetro	Valor	Descrição
Capacidade	500 tokens	Máximo de tokens no bucket (permite bursts).
Reposição	500 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 um produto.
Query média (5-14 campos)	3 tokens	Queries com múltiplos campos.
Query complexa (15+ campos)	5 tokens	Queries com muitos relacionamentos.
Mutation (insert/update)	10 tokens	Criar ou atualizar produto.
Mutation (delete)	10 tokens	Remover produto.
Mutation com imagens	20 tokens	Mutations que incluem upload de imagens base64.
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 (500).
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 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

Recurso	Limite	Descrição
Tamanho do body	2 MB	Tamanho máximo do payload por request.
Profundidade de query	7 níveis	Profundidade máxima de aninhamento.
Imagens por request	10	Má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;
}