Limiti di frequenza

Certivant applica un limite di richieste API al minuto per proteggere la piattaforma da client fuori controllo e da carichi molesti di altri clienti. Resti entro il limite e non vedrà mai un throttling; se lo supera riceve un 429 con intestazioni che indicano esattamente quando riprovare.

Il limite

Il tetto al minuto è definito dal Suo piano. L'operatore della piattaforma può anche concedere una deroga per cliente, che è sempre limitata al massimale del piano. Il numero effettivo è quello che l'intestazione X-RateLimit-Limit riporta su ogni risposta — la legga invece di impostare un valore fisso nel codice.

Tetti predefiniti per piano

Sono valori predefiniti: l'operatore della piattaforma può modificare il tetto per piano e concedere alla Sua organizzazione un limite per cliente più alto (fino al tetto del piano). Il limite effettivo della Sua organizzazione, in sola lettura, è visibile nella dashboard in KYC → Sviluppatore.

Se per il traffico di produzione Le serve un tetto più alto, chieda al Suo referente account (oppure, nelle installazioni self-hosted, all'operatore della piattaforma) di aumentare il tetto del piano o il limite per cliente.

Intestazioni di risposta (su ogni risposta autenticata)

Ogni risposta riuscita include lo stato attuale del limite:

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
Content-Type: application/json

{ "data": [...], "pagination": {...} }

Legga questi valori nel Suo client per rallentare in anticipo — non attenda un 429 se vede X-RateLimit-Remaining: 3.

La risposta 429

Quando supera il limite, la richiesta successiva restituisce:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Max 120 requests per 60s. Retry in 18s."
  }
}

X-RateLimit-Reset indica esattamente quanto attendere. La usi invece di tirare a indovinare.

Strategia di nuovo tentativo

Il gestore più semplice e corretto:

async function withRateLimit<T>(fn: () => Promise<Response>): Promise<T> {
  while (true) {
    const res = await fn();
    if (res.status !== 429) {
      if (!res.ok) throw await readError(res);
      return res.json() as Promise<T>;
    }
    const retryAfterSec = Number(res.headers.get("X-RateLimit-Reset") ?? 60);
    await sleep(retryAfterSec * 1000 + 100); // pad by 100ms for clock skew
  }
}

Tre proprietà da rispettare:

1. Rispetti X-RateLimit-Reset. Un'attesa più breve colpisce di nuovo il limite.
2. Aggiunga circa 100 ms per tenere conto dello scostamento dell'orologio tra la Sua macchina e l'edge di Certivant.
3. Limiti i nuovi tentativi se la richiesta non è critica. Insistere per 5 minuti su una chiamata di elenco non urgente spreca risorse da entrambe le parti.

Progettare intorno al limite

Il risparmio maggiore viene dall'uso dei webhook. La prima causa dei ticket di supporto «sto raggiungendo il limite di frequenza» sono le integrazioni che interrogano per conoscere i cambiamenti di stato — non lo faccia: configuri invece i webhook.

Comportamento a raffica

Il limite viene applicato come finestra fissa: la prima richiesta avvia un contatore di 60 secondi, e ogni richiesta conta sul tetto fino alla fine della finestra. Distribuisca il traffico continuativo in modo uniforme, invece di esaurire il budget di un minuto nei primi secondi.

Se conosce un modello di raffica (per esempio un job batch giornaliero che elabora 500 record), distanzi le chiamate:

for (const record of records) {
  await processOne(record);
  await sleep(500); // 2 req/s — comfortably under typical ceilings
}

Che cosa succede quando Redis non è raggiungibile

Se l'istanza Redis del limite di frequenza è temporaneamente irraggiungibile, Certivant fallisce in apertura — non blocca il Suo traffico. Vedrà risposte 2xx normali senza le intestazioni X-RateLimit-*. Quando Redis torna disponibile, riprende la normale applicazione del limite. Ciò significa che un'interruzione di Redis dalla nostra parte non interrompe la Sua integrazione.

I webhook sono separati

Il limite di frequenza si applica alle Sue chiamate in uscita verso Certivant. Le consegne dei webhook in entrata da Certivant verso il Suo endpoint non consumano alcuna quota. Non c'è alcun «limite di frequenza dei webhook» di cui preoccuparsi.

Endpoint pubblici

Gli endpoint che non richiedono una chiave API (GET /api/status, GET /api/kyc/public/status, gli endpoint di invio dei moduli) hanno un limite per IP separato di 60 richieste al minuto. Si applica all'indirizzo IP del chiamante, non a una chiave API. È impostato in modo prudente perché questi endpoint sono raggiungibili senza autenticazione; se l'interfaccia rivolta ai richiedenti li sta colpendo, instradi le chiamate attraverso il Suo backend, così condividono un IP sotto il Suo controllo.