API e desenvolvedores

Rate Limiting

Entenda os limites de requisições e como lidar com respostas 429

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

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.
Precisa de ajuda?