Limiti di frequenza

Limiti di richieste per piano condivisi tra Listings e Social, struttura della risposta 429 e modalità di attesa progressiva e di nuovo tentativo.

La Listings API conteggia le richieste per account rispetto al limite di frequenza del tuo piano. Rispettare il limite mantiene reattiva la tua integrazione; superarlo restituisce 429 Too Many Requests con tutto il necessario per riprovare correttamente.

Limiti per piano

Stai provando l'API senza un piano a pagamento? Il pass giornaliero gratuito per la sandbox restituisce i limiti di richieste in vigore insieme alla chiave API quando attivi il pass.

I limiti dipendono dal piano e vengono applicati per account: tutte le chiavi API di un account attingono allo stesso contingente. Le richieste vengono conteggiate su tre intervalli: un limite al minuto per i picchi di richieste, un limite orario e un tetto giornaliero. Ogni richiesta ha lo stesso costo, indipendentemente dall'endpoint. La prova gratuita usa il piano che hai scelto, quindi ne applica i limiti fin dalla prima richiesta.

Social attinge allo stesso contingente

Le richieste agli endpoint Social vengono conteggiate nello stesso contingente di richieste per account di tutte le altre. Un POST /social/bulk-posts contenente 500 righe costa una richiesta, non 500, quindi le operazioni in blocco sono il modo più economico per caricare molti contenuti.

Listings e Social sono abbonamenti separati, ma non hanno contingenti separati. A un account che dispone di entrambi vengono assegnati i limiti più alti tra quelli dei due livelli, applicati una sola volta a tutti gli endpoint, senza sommarli e senza assegnare un contingente per prodotto. Tutto il traffico di un cliente con Listings Launch e Social Growth viene conteggiato secondo i valori di Growth indicati sopra.

La risposta 429

Quando superi un limite, l'API restituisce lo stato HTTP 429 e la risposta di errore standard. Tre campi sono rilevanti per i nuovi tentativi:

• retry_after_seconds: quanto tempo attendere prima di riprovare. L'header HTTP Retry-After contiene lo stesso valore, quando presente.
• correlation_id: un identificatore della richiesta da citare se contatti l'assistenza.
• doc_url: un link alla voce rate_limited nella documentazione di riferimento dei codici di errore.

{  "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"  }}

Gestire le risposte 429 con un'attesa progressiva

Rispetta retry_after_seconds quando è presente; altrimenti, aumenta l'attesa in modo esponenziale: raddoppia il ritardo a ogni 429 consecutivo fino a un limite massimo, aggiungendo una piccola variazione casuale per evitare che un insieme di client riprovi contemporaneamente.

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")

Rimanere entro il limite

• Richiedi una pagina alla volta: i cicli di paginazione paralleli con richieste ravvicinate sono la causa più comune delle risposte 429. Leggi pageInfo.hasNextPage e recupera la pagina successiva solo dopo aver ricevuto la risposta per quella corrente.
• Filtra lato server con il parametro di query filter invece di recuperare tutte le pagine e scartare le righe lato client.
• Memorizza nella cache le risposte che cambiano di rado invece di recuperarle di nuovo a ogni richiesta.