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.

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 successivaGET account