Vai al contenuto

API ecentic: limiti di frequenza.

Ogni risposta pubblica include lo stato live della finestra corrente, così un agente può regolarsi senza scoprire il limite tramite un rifiuto.

Header live · Retry-After su 429 · Finestre per chiave

01

La policy

Una finestra fissa sulla superficie pubblica, conteggiata per credenziale.

public

Ogni endpoint /api/v1

120richieste

ogni 60 secondi

news

/api/v1/news

30richieste

ogni 60 secondi

news-resolve

/api/v1/news?resolve=true

6richieste

ogni 60 secondi

Le richieste che includono una bearer key vengono conteggiate rispetto a quella chiave; tutto il resto viene conteggiato rispetto all'IP del client, così un agente con traffico eccessivo non può consumare il budget di un indirizzo condiviso.

La finestra è fissa, non scorrevole: si reimposta su un confine temporale assoluto e il valore reset negli header indica il numero di secondi mancanti a quel confine.

Policy applicate dall’API
02

Header

Vengono inviate entrambe le varianti. Usa quella già supportata dal tuo client.

RateLimit-Policy è sempre presente, perché la policy è valida indipendentemente dal fatto che una richiesta specifica possa essere conteggiata. I contatori live vengono inviati solo quando esiste un conteggio reale — un ambiente che non riesce a raggiungere il contatore li omette invece di dichiarare un budget che nessuno ha misurato.

Seleziona un header per leggerne il significato. Questi valori illustrano una risposta; non sono un contatore in tempo reale.

HeaderEsempio

Significato: La policy attiva: quota e durata della finestra in secondi.

Un solo limite, due interpretazioni

In questo esempio, entrambi i formati di header descrivono la stessa finestra.

Richieste rimanenti
118
r=118 · RateLimit-Remaining
Secondi al ripristino
42
t=42 · RateLimit-Reset
03

Quando superi il limite

Un 429 è un problema tipizzato come qualsiasi altro errore.

La risposta è application/problem+json con codice rate-limited e include Retry-After insieme agli header di rate limit. Attendi il numero di secondi indicato invece di riprovare subito — un nuovo tentativo nella stessa finestra viene conteggiato e rifiutato di nuovo.

Esempio: risposta 429