Rate Limiting

A Business API aplica limites de requisições por merchant para garantir uso justo e estabilidade da plataforma.

Headers de Resposta

Cada resposta inclui headers de rate limit que indicam sua cota atual:

Header	Descrição
`X-RateLimit-Limit`	Máximo de requisições permitidas na janela atual
`X-RateLimit-Remaining`	Requisições restantes na janela atual
`X-RateLimit-Reset`	Timestamp Unix quando a janela reinicia

Consulte esses headers em cada resposta para conhecer seu limite e quantas requisições restam.

Lidando com 429 Too Many Requests

Quando você excede o limite, a API responde com status 429 e adiciona um header Retry-After:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710288000

{
  "type": "RateLimitExceededError",
  "detail": "Rate limit exceeded"
}

Estratégia de Retry

Use backoff exponencial quando receber uma resposta 429:

import time
import httpx

def request_with_retry(url: str, headers: dict, max_retries: int = 3):
    for attempt in range(max_retries):
        response = httpx.get(url, headers=headers)
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        time.sleep(retry_after)
    return response

async function requestWithRetry(url, headers, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, { headers });
    if (response.status !== 429) return response;
    const retryAfter = parseInt(response.headers.get("Retry-After") || 2 ** attempt);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
  }
}

Boas Práticas

Monitore o header X-RateLimit-Remaining para reduzir a velocidade proativamente antes de atingir o limite.
Faça cache das respostas quando os dados não mudam frequentemente — especialmente catálogos de produtos.
Agrupe seu trabalho — solicite páginas maiores (até limit=100) para reduzir o número de requisições.
Respeite o Retry-After — sempre espere o tempo indicado antes de tentar novamente, em vez de usar um delay fixo.