Concetti di base

Rate limit

Ogni chiave può fare 120 richieste al minuto, e ogni risposta indica quante ne restano.

Limiti

Limite	Si applica a
120 richieste al minuto	Ogni chiave API, su ogni endpoint. Il minuto è una finestra fissa che parte allo scoccare del minuto.
10 export all'ora	Ogni account, su Crea un export. Oltre il limite, 429 `export_rate_limit_exceeded`.
10 DM al minuto	Ogni account X, su Invia un messaggio. Oltre il limite, 429 `dm_rate_limited`.
300 DM al giorno	Ogni account X, per giorno UTC, o meno se X impone una quota più bassa. Oltre il limite, 429 `dm_daily_limit`.
5 tentativi di codice all'ora	Ogni account, su Imposta il codice X Chat. Oltre il limite, 429 `passcode_rate_limited`.
6 messaggi a Julien AI al minuto	Ogni account X, su Invia un messaggio e sul tool MCP `ask_julien_ai`. Oltre il limite, 429 `assistant_rate_limited`.
100 messaggi a Julien AI al giorno	Ogni account X, per giorno UTC. Oltre il limite, 429 `assistant_daily_limit`.
Un messaggio a Julien AI alla volta	Ogni chat, e 3 chat in contemporanea per ogni account X. Oltre il limite, 409 `assistant_busy`.

Header di rate limit

Ogni risposta riporta lo stato della finestra della chiave.

Header	Significato
`RateLimit-Limit`	Richieste consentite in una finestra, `120`.
`RateLimit-Remaining`	Richieste rimaste nella finestra corrente.
`RateLimit-Reset`	Secondi prima che la finestra riparta.
`Retry-After`	Solo su un 429, i secondi da attendere prima di riprovare.

Header

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 17
Retry-After: 17
Request-Id: req_3Vb8YzC1dF6hJ0sW

Risposta429

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. This key can make 120 requests a minute.",
    "param": null,
    "request_id": "req_3Vb8YzC1dF6hJ0sW",
    "doc_url": "https://gemlead.ai/docs/errors#rate_limit_exceeded"
  }
}

Gestisci un 429

Attendi Retry-After secondi, poi invia di nuovo la stessa richiesta.

Distribuisci i lavori pesanti nel tempo invece di inviarli a raffica.
Leggi RateLimit-Remaining per rallentare prima di arrivare a zero.
Per scaricare molti lead in una volta, un solo export vale più di centinaia di pagine.
I webhook ti inviano gli eventi, così non sprechi mai richieste per fare polling di nuovi lead.

# curl waits for Retry-After, then tries again
curl --retry 5 https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"