Rate Limiting

Per garantire stabilità e disponibilità a tutti gli utenti, le API di Sibill applicano dei limiti sul numero di richieste che un client può effettuare in un determinato intervallo di tempo. Quando il limite viene superato, ulteriori richieste vengono temporaneamente rifiutate finché la finestra non si rinnova.

Il rate limiting viene applicato per token di autenticazione: ogni token dispone della propria quota di richieste indipendente.

Header di risposta

Ogni risposta delle API include alcuni header HTTP che permettono di monitorare lo stato della quota e di reagire correttamente in caso di superamento del limite.

Header	Descrizione
x-ratelimit-limit	Numero massimo di richieste consentite nella finestra temporale corrente.
x-ratelimit-remaining	Numero di richieste ancora disponibili nella finestra temporale corrente.
retry-after	Numero di secondi da attendere prima di poter effettuare una nuova richiesta. Presente solo in caso di 429.

Superamento del limite

Quando il numero di richieste supera il limite consentito, le API rispondono con il codice di stato HTTP 429 Too Many Requests. In questo caso, l'header x-ratelimit-remaining sarà 0 e l'header retry-after indicherà il numero di secondi da attendere prima di poter effettuare nuovamente la richiesta.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
retry-after: 30

{
   "errors":[
      {
         "code":"too_many_requests",
         "detail":"Rate limit exceeded. Retry after 30 seconds.",
         "title":"Too Many Requests"
      }
   ]
}

Come gestire il rate limiting

Per evitare di incorrere in errori 429 e per gestire correttamente il superamento del limite, è consigliato seguire queste pratiche:

• Monitora gli header: controlla x-ratelimit-remaining per sapere quante richieste hai ancora a disposizione nella finestra corrente e adatta di conseguenza la frequenza delle chiamate.
• Rispetta l'header retry-after: in caso di risposta 429, attendi il numero di secondi indicato prima di rieffettuare la richiesta. Non tentare nuove chiamate prima di tale intervallo, in quanto verranno ugualmente rifiutate.
• Implementa una strategia di retry con backoff: in caso di errori 429 ripetuti, utilizza un meccanismo di exponential backoff per distribuire le richieste nel tempo ed evitare di saturare nuovamente il limite.
• Evita richieste in parallelo non necessarie: raggruppa le chiamate quando possibile e utilizza la paginazione e i filtri per ridurre il numero totale di richieste.

Esempio di gestione

Di seguito un esempio di come gestire una risposta 429 in pseudocodice:

response=$(curl -i --request GET \
     --url {{BASE_URL}}/api/v1/companies \
     --header "Authorization: Bearer {{TOKEN}}")

status=$(echo "$response" | head -n 1 | awk '{print $2}')

if [ "$status" = "429" ]; then
   retry_after=$(echo "$response" | grep -i "^retry-after:" | awk '{print $2}' | tr -d '\r')
   echo "Rate limit raggiunto. Riprovo tra ${retry_after} secondi..."
   sleep "$retry_after"
fi