Rate limiting

Le API GipoNext applicano un limite al numero di richieste che un'applicazione può inviare in un determinato intervallo di tempo. Questo meccanismo, detto rate limiting, protegge la stabilità del servizio per tutti gli integratori e per le cliniche.

Questa pagina spiega come funziona il rate limiter, quale risposta HTTP produce e come gestirlo correttamente nel tuo codice.

Come funziona

Il rate limiter conta le richieste per client OAuth (identificato dal client_id) in finestre temporali scorrevoli. Quando il numero di richieste supera la soglia consentita, le richieste in eccesso vengono rifiutate fino al termine della finestra corrente.

Il limite si applica all'intera applicazione, indipendentemente da quanti utenti stiano usando la tua app in contemporanea. Se hai più utenti che eseguono operazioni nello stesso momento, le loro richieste concorrono tutte allo stesso contatore.

La risposta HTTP: 429 Too Many Requests

Quando superi il limite, il server risponde con:

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

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after the indicated time."
}

Header da leggere

Header	Descrizione
Retry-After	Secondi da attendere prima di riprovare la richiesta. Rispetta sempre questo valore.

⚠️ Leggi sempre Retry-After

Non riprovare immediatamente dopo un 429. Il server indica esplicitamente quanto aspettare tramite l'header Retry-After.

Ignorarlo e riprovare subito porta a nuovi 429, aggrava il problema e può prolungare il blocco.

Perché aggiungere il jitter?

Se più istanze della tua applicazione ricevono un 429 nello stesso momento e riprovano tutte esattamente dopo lo stesso numero di secondi, il picco di traffico si ripresenta identico. Aggiungere una piccola variazione casuale (jitter) distribuisce i retry nel tempo e riduce la probabilità di una nuova collisione.

Buone pratiche per non raggiungere il limite

Usa i refresh token invece di richiedere nuovi token continuamente

Il token endpoint è soggetto a rate limiting come tutti gli altri endpoint. Richiedi un nuovo access token solo quando quello attuale è scaduto; non chiamare il token endpoint a ogni richiesta API.

Metti in coda le operazioni batch

Se devi elaborare grandi volumi di dati (es. sincronizzazione di pazienti), non inviare tutte le richieste in parallelo. Usa una coda con un ritmo controllato (es. N richieste al secondo), così rimani sotto la soglia.

Non fare polling aggressivo

Se hai bisogno di sapere quando un dato cambia, evita polling aggressivo interrogando l'api ogni minuto. Usa intervalli ragionevoli, oppure adotta un approccio on-demand (interroga solo quando l'utente lo richiede).

Comportamento in caso di errori ripetuti

Se continui a ricevere 429 nonostante il rispetto dei Retry-After, considera che:

• Stai eseguendo troppo parallelismo — riduci il numero di richieste concorrenti.
• Hai più istanze della stessa applicazione che condividono lo stesso client_id — le loro richieste si sommano.
• Hai un bug nel codice che genera richieste in loop — controlla che non ci siano chiamate ridondanti o cicli non terminanti.

Se il problema persiste, contatta il supporto descrivendo il volume di richieste e l'endpoint interessato.

Prossimi passi

• Flussi OAuth e token — come gestire la scadenza dei token senza chiamare il token endpoint inutilmente
• Entità e operazioni — risorse disponibili, scope e note operative