Limiti di frequenza delle API

Elido applica i limiti di frequenza dell'API per chiave, non per workspace. Ciò significa che ogni integrazione che costruisci può saturare il proprio limite senza privare le altre. Questo articolo tratta i limiti per piano, gli header da leggere e come effettuare il backoff in modo pulito.

I numeri#

Limiti sostenuti per chiave:

Piano	Al minuto	Burst
Free	60	120
Pro	600	1200
Business	6000	12000

Il burst è ciò che puoi superare brevemente in una finestra di 10 secondi. Il sostenuto è il limite allo stato stazionario con cui si ricarica il bucket.

Non ci sono limiti per endpoint — una GET /v1/links conta quanto una POST /v1/links. Le uniche eccezioni sono:

• POST /v1/bulk-import — 5 importazioni attive per workspace alla volta.
• POST /v1/links con uno slug personalizzato che collide con uno esistente — contano comunque ma non rimborsa lo slot in caso di conflitto.
• GET /v1/analytics/timeseries con interval=second — limitato a 60/minuto anche su Business, perché la query ClickHouse sottostante è più pesante.

Header di risposta#

Ogni risposta API include:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset è un timestamp Unix che indica quando il bucket si ricarica completamente. Usalo per pianificare i tentativi di ripetizione anziché ritardi fissi.

Come appare un 429#

Quando superi il limite:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After è in secondi. Attendi quel tempo, poi riprova. Gli SDK lo fanno automaticamente con jitter; se stai scrivendo un client HTTP raw, fai lo stesso.

Strategia di backoff#

Se stai martellando l'API (un lavoro bulk una tantum, un backfill), regola il ritmo del client al limite sostenuto anziché al burst. Un loop ingenuo colpisce il limite burst, poi si blocca per 50 secondi, poi colpisce di nuovo il burst — ottenendo mediamente risultati peggiori rispetto a un ritmo costante.

Pseudocodice:

const limit = 600; // per minute
const delayMs = (60 * 1000) / limit; // 100ms between requests

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Questo pattern usa il 100% del limite senza nessun 429.

Concorrenza#

Le richieste concorrenti condividono il bucket. Se invii 100 richieste parallele da un pool di worker sul piano Pro (600/min), le prime 100 riescono immediatamente; il bucket si ricarica poi a 10/sec. Il tuo pool di worker dovrebbe mirare a un ritmo sostenuto, non a una profondità di coda.

Per chiave vs per IP#

Il bucket è per chiave, non per IP. Se stai usando la stessa chiave da 10 macchine, le 10 macchine condividono il limite. Emetti una chiave per macchina se hai bisogno di 10× headroom.

Il livello IP ha un limite separato, molto generoso (10.000/min/IP) inteso solo per fermare i client impazziti. Non lo raggiungerai mai in uso normale; se lo fai, la risposta è 429 con il corpo "error": "ip_rate_limited".

Le chiavi di idempotenza non aggirano i limiti#

Inviare lo stesso Idempotency-Key ripetutamente conta comunque ogni richiesta nel tuo bucket — possiamo restituire la risposta memorizzata senza eseguire il lavoro sottostante, ma il conteggio viene incrementato. Non usare le chiavi di idempotenza in loop come strategia di ripetizione.

Aumentare i limiti#

Se il tuo caso d'uso richiede genuinamente più di 6000/min sostenuti, scrivi a support@elido.app con:

• L'ID del tuo workspace.
• Il nome dell'integrazione.
• La velocità di richiesta prevista allo stato stazionario e al picco.
• Gli endpoint coinvolti (così possiamo pianificare la capacità per quelli pesanti).

Concediamo aumenti dei limiti per chiave ai clienti enterprise sotto contratto, di solito entro un giorno lavorativo.

Risoluzione dei problemi#

Improvvisamente ricevo 429 su una chiave che funzionava prima. Il tuo codice ha iniziato a fare loop (caso più comune), oppure qualcun altro nel workspace ha iniziato a usare la stessa chiave. Controlla la scheda Utilizzo della chiave API nella dashboard per un grafico al minuto.

429 alla prima richiesta del giorno. I bucket del piano gratuito si reimpostano su una finestra temporale mobile, non a mezzanotte UTC. Se hai testato il limite ieri alle 23:59 e non si è ricaricato completamente alle 00:01, il primo burst è ancora limitato. Aspetta 60 secondi.

X-RateLimit-Remaining è negativo. Sforamento del burst. Il numero indica quanto sei in negativo; moltiplicalo per 60/limit per ottenere i secondi prima di tornare a zero.