API rate limits and quotas — Italy
Token-bucket limits, burst behaviour and 429 handling for the Corp-Merch REST API in Italy.
Architecture — Per-key, per-route limits for Italy
Each API key has its own token bucket per route. Defaults: Standard tier 600 req/min on /v1/orders and /v1/invoices, 1,200 req/min on read-only endpoints; Pro tier 10x. Bursts up to 2x allowed for 10 seconds. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers. SdI invoice issuance is asynchronous and not rate-limited at submission — only at status polling. IVA 22% computation is uncapped.
How to wire it up — 429 responses and Retry-After
When you exceed your limit we return 429 Too Many Requests with a Retry-After header in seconds. Our SDKs handle this automatically with exponential backoff and jitter; if you build a custom client, mirror that logic and never busy-loop. Sustained 429s for >5 minutes auto-page our customer-success team — we would rather raise your limit than have you fail.
Operations and edge cases — Quotas and fair use
On top of rate limits, monthly quotas cap total orders, invoices, and webhook deliveries per tenant — sized to your contract. Soft quotas warn at 80% and 100% via dashboard and email; hard quotas (rare, only on free trials) reject with 402 Payment Required. Catalog reads and Sistema di Interscambio (SdI) status polling are uncapped on paid plans.
FAQ
Can I get a higher limit?
Yes — for Pro and Enterprise we adjust limits in line with your contracted volumes. Reach out to support with a sustained-load profile.
Are read-only endpoints lighter?
Yes — read endpoints (GET /v1/catalog, GET /v1/orders) have 2x the limit of write endpoints by default.
What about webhook deliveries?
Webhook throughput is on a separate budget — we deliver at up to 50/s per endpoint with backpressure; you don't pay for inbound.
Burst handling?
Token bucket allows 2x burst for ~10 seconds, then steady-state limit applies. Good for end-of-month batch jobs.
SdI polling?
Polling /v1/invoices/{id} status is rate-limited like other reads; we recommend webhooks instead for the SdI acknowledgement.