Limites de requisições

Limites de requisições por plano para Listings e Social, o formato da resposta 429 e como aumentar o intervalo entre novas tentativas.

A Listings API contabiliza as requisições por conta em relação ao limite de requisições do seu plano. Respeitar o limite mantém sua integração responsiva; ultrapassá-lo retorna 429 Too Many Requests com tudo de que você precisa para tentar novamente de forma adequada.

Limites por plano

Você está experimentando a API sem um plano pago? O passe diário gratuito do sandbox retorna os limites de requisições vigentes junto com a chave de API quando você inicia o passe.

Os limites são definidos pelo plano e aplicados por conta: todas as chaves de API de uma conta consomem a mesma cota. As requisições são contabilizadas em três janelas: um limite de pico por minuto, um limite por hora e um limite diário. Todas as requisições têm o mesmo custo, independentemente do endpoint. O período de teste gratuito usa o plano que você escolheu, portanto os limites desse plano se aplicam desde a primeira requisição.

Social consome a mesma cota

Os endpoints de Social são contabilizados na mesma cota de requisições por conta que todos os demais endpoints. Uma requisição POST /social/bulk-posts com 500 linhas custa uma requisição, não 500, portanto as operações em lote são a forma mais econômica de carregar uma grande quantidade de conteúdo.

Listings e Social são assinaturas separadas, mas não têm cotas separadas. Uma conta com ambas recebe os limites do maior dos dois planos, aplicados uma única vez a todos os endpoints — não a soma, nem uma cota por produto. Um cliente com Listings Launch e Social Growth tem todo o seu tráfego contabilizado de acordo com os limites de Growth apresentados acima.

A resposta 429

Quando você excede um limite, a API retorna o status HTTP 429 e a resposta de erro padrão. Três campos são relevantes para novas tentativas:

• retry_after_seconds: quanto tempo esperar antes de tentar novamente. O cabeçalho HTTP Retry-After contém o mesmo valor quando está presente.
• correlation_id: um identificador de requisição que você deve informar se entrar em contato com o suporte.
• doc_url: um link para a entrada rate_limited na referência de códigos de erro.

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Como lidar com respostas 429 usando intervalos progressivos

Respeite retry_after_seconds quando estiver presente e, caso contrário, aumente o intervalo exponencialmente: dobre o tempo de espera a cada 429 consecutivo até um limite máximo, com uma pequena variação aleatória para que um conjunto de clientes não tente novamente ao mesmo tempo.

import randomimport time import requests MAX_RETRIES = 5  def get_with_backoff(url: str, headers: dict, max_retries: int = MAX_RETRIES):    for attempt in range(max_retries):        resp = requests.get(url, headers=headers)        if resp.status_code != 429:            resp.raise_for_status()            return resp.json()         # Prefer the server's hint; fall back to exponential backoff + jitter.        body = resp.json().get("error", {})        retry_after = body.get("retry_after_seconds")        if retry_after is None:            retry_after = min(2 ** attempt, 30) + random.uniform(0, 1)        time.sleep(retry_after)     raise RuntimeError("Still rate limited after retrying")

Como ficar abaixo do limite

• Solicite uma página por vez: loops de paginação em paralelo sem intervalos são a causa mais comum de respostas 429. Leia pageInfo.hasNextPage e só busque a próxima página quando a requisição da página atual retornar.
• Filtre no servidor com o parâmetro de consulta filter em vez de buscar todas as páginas e descartar linhas no cliente.
• Armazene em cache as respostas que mudam com pouca frequência em vez de buscá-las novamente a cada requisição.