Comprendere le richieste API e la quota

Il tuo piano di abbonamento include una quota mensile di richieste. Questa pagina spiega esattamente cosa conta come richiesta, quali endpoint sono gratuiti e cosa succede quando raggiungi il limite.

Cos'è 1 richiesta?

1 richiesta = 1 chiamata a un endpoint API fatturabile, indipendentemente dalla risposta.

Ogni chiamata riuscita a un endpoint fatturabile conta esattamente come una richiesta sulla tua quota. La dimensione della risposta, il numero di elementi restituiti, i parametri di query o lo stato HTTP non hanno alcun effetto sul conteggio — una chiamata che restituisce 1.000 fixture e una che ne restituisce 0 consumano entrambe esattamente 1 richiesta.

Le richieste vengono conteggiate per abbonamento, quindi tutte le chiamate effettuate con la tua chiave API si sommano sulla stessa quota.

La quota gratuita si azzera il 1° giorno di ogni mese.

Quali endpoint contano?

Endpoint fatturabili (conteggiati nella tua quota)

Ogni chiamata a questi endpoint usa 1 richiesta:

/v4/players
/v4/settlements
/v4/fixtures
/v4/fixture
/v4/odds-by-tournaments
/v4/languages
/v4/sports
/v4/bookmakers
/v4/markets
/v4/tournaments
/v4/participants
/v4/scores
/v4/odds

Endpoint gratuiti (NON conteggiati nella tua quota)

/v4/historical-odds — sempre gratuito. Le chiamate non incrementano mai il tuo contatore di richieste.

Endpoint non misurati (NON conteggiati e mai bloccati)

/v4/account — sempre accessibile, anche dopo aver esaurito la quota. In questo modo puoi sempre verificare lo stato dell'abbonamento e la quota residua.

Quando viene conteggiata una richiesta?

Una richiesta viene conteggiata dopo che l'endpoint ha completato l'elaborazione, indipendentemente dal fatto che la risposta sia andata a buon fine o abbia restituito un errore. Questo include:

200 OK — risposte riuscite
4xx — errori del client (ad es. parametri non validi, risorsa non trovata)
5xx — errori del server

Nota

Le richieste rifiutate prima di raggiungere l'endpoint — ad esempio perché la chiave API non è valida o la quota è già esaurita — non vengono conteggiate.

Raggiungimento del limite

Quando il conteggio accumulato raggiunge il valore request_limit del tuo piano, ogni chiamata successiva a un endpoint fatturabile o gratuito (eccetto /v4/account) restituirà immediatamente:

HTTP/1.1 429 Too Many Requests

{
  "message": "Request limit exceeded",
  "details": "You have exceeded your request limit of X requests.",
  "code": "REQUEST_LIMIT_EXCEEDED"
}

Puoi continuare a chiamare /v4/account in qualsiasi momento per controllare l'abbonamento, l'uso attuale e quando la quota viene resettata.

Controllare il tuo utilizzo

Chiama GET /v4/account in qualsiasi momento. La risposta include, per il tuo abbonamento attivo:

request_limit — la quota del tuo piano
request_count — quante richieste fatturabili hai consumato nel periodo corrente

Consigli per ridurre il consumo di richieste

Metti in cache le risposte lato client quando i dati sottostanti cambiano di rado (ad es. /v4/sports, /v4/bookmakers, /v4/markets, /v4/languages).
Raggruppa quando possibile — usa /v4/fixtures con filtri invece di molte chiamate singole quando ti servono più fixture contemporaneamente.
Esegui il polling in modo responsabile — ogni poll a un endpoint fatturabile è 1 richiesta, quindi allinea l'intervallo di polling alla frequenza con cui i dati cambiano davvero.

Pagina precedenteOverview

Pagina successivaErrors