Limiti di richieste

Nembol usa un leaky bucket per ogni chiave API (lo stesso modello di Shopify): puoi inviare un picco di richieste fino alla capienza del bucket, e il bucket si svuota a un ritmo costante.

Partner: con l'header Nembol-Account, ogni azienda ha il proprio bucket, quindi un'azienda molto attiva non rallenta mai le altre. La sua capienza dipende dal piano di quell'azienda, non dal tuo. Le chiamate senza l'header (il tuo negozio, /accounts, /partner/*) usano il bucket della chiave, dimensionato in base al tuo piano.

Oltre al limite di richieste c'è una quota giornaliera di scritture sulle richieste che modificano i canali (scritture di prodotti, aggiornamenti dell'inventario, pubblicazione/rimozione), perché ogni scrittura consuma anche le quote API dei tuoi canali. Il tuo utilizzo attuale è visibile nella dashboard in Impostazioni → Sviluppatori → Utilizzo.

Header

Ogni risposta ti dice a che punto sei. Usa gli header per rallentare prima di arrivare al 429:

X-RateLimit-Limit: 40
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1784900412

Remaining indica quante richieste ci stanno in questo momento. Reset è il secondo (epoch Unix) in cui il bucket è di nuovo completamente pieno (tutte le richieste di Limit disponibili), non il prossimo slot libero: subito dopo un 429 può mancare molto tempo, mentre una singola richiesta ci sta già di nuovo. Per sapere quando ci sta la prossima richiesta, usa Retry-After sul 429.

Quando ricevi un 429

{ "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "…" } }

La risposta contiene Retry-After (in secondi, esatto, calcolato dal bucket e non stimato). Attendi quel tempo e riprova. Per un throughput costante, distribuisci le richieste al ritmo sostenuto invece di alternare picchi e pause.

write_quota_exceeded (anche questo 429) significa che la quota giornaliera di scritture è esaurita. Si azzera a mezzanotte UTC; le letture continuano a funzionare.

I limiti dei canali contano più dei nostri

Ogni scrittura di prodotti o inventario finisce per chiamare le API dei tuoi canali, che hanno i propri limiti (spesso molto più stretti). I worker di Nembol li rispettano automaticamente. Quando un canale limita le richieste, l'operazione riporta channel_rate_limited e Nembol riprova con backoff. Gli endpoint batch (POST /inventory/batch) sono il modo efficiente per fare aggiornamenti in blocco: una richiesta API, chiamate ai canali distribuite in modo ottimale.

Ultimo aggiornamento il 21 ottobre 2026