Limiti di chiamata API e quote — Italia
Limiti token-bucket, comportamento burst e gestione 429 per la REST API Corp-Merch in Italia.
Architettura — Limiti per chiave e per rotta in Italia
Ogni API key ha un proprio token bucket per rotta. Default: Standard 600 req/min su /v1/orders e /v1/invoices, 1.200 req/min sulle rotte read-only; Pro 10x. Burst 2x consentito per 10 secondi. Le risposte includono X-RateLimit-Limit, -Remaining, -Reset. L'emissione fattura SdI è asincrona e non rate-limited al submit — solo al polling stato. Il calcolo IVA 22% non è limitato.
Come integrarlo — Risposte 429 e Retry-After
Al superamento del limite torniamo 429 Too Many Requests con header Retry-After in secondi. I nostri SDK gestiscono il backoff esponenziale con jitter; se costruisci un client custom, replica la logica e non fare busy-loop. 429 prolungati > 5 minuti notificano automaticamente il CS team — preferiamo alzare il limite anziché vederti fallire.
Operatività e casi limite — Quote e fair use
Oltre ai rate limit, quote mensili limitano ordini, fatture e webhook per tenant — dimensionate al contratto. Soft quota: avvisi all'80% e 100% via dashboard ed email; hard quota (rare, solo trial) restituiscono 402 Payment Required. Letture catalogo e polling stato Sistema di Interscambio (SdI) senza limite sui piani a pagamento.
Domande frequenti
Posso ottenere un limite più alto?
Sì — per Pro ed Enterprise allineiamo i limiti ai volumi contrattuali. Contatta il support con un profilo di carico sostenuto.
Le rotte read-only sono più leggere?
Sì — gli endpoint di lettura (GET /v1/catalog, GET /v1/orders) hanno 2x il limite delle scritture per default.
E i webhook?
Il throughput webhook ha budget separato — fino a 50/s per endpoint con backpressure; l'inbound non si paga.
Gestione burst?
Il token bucket permette 2x burst per ~10 secondi, poi si applica il limite steady-state. Utile per i job di fine mese.
Polling SdI?
Il polling di /v1/invoices/{id} è rate-limited come le altre letture; consigliamo i webhook per la notifica SdI.