Quote e limiti

La quota dipende dal tuo piano. Una richiesta = 1 unità, indipendentemente dal numero di righe restituite. Il contatore si azzera all’inizio di ogni ora (UTC).

Piano	Richieste / ora
Prova (account senza abbonamento)	250
Starter	1.000
Pro	10.000
Sharp	20.000

Accesso per piano

Alcuni endpoint sono riservati ai piani superiori:

Funzionalità	Starter	Pro	Sharp
Quote prematch + live, fixtures, storico, opening/closing, risultati	✓	✓	✓
Specials (`/api/specials/*`)	—	—	✓
Flussi in tempo reale (`/api/stream`, `/api/stream/event`, `/api/stream/odds`, `/api/stream/mqtt`)	—	—	✓

Chiamare un endpoint fuori dal tuo piano restituisce 403:

403

{
  "detail": "Endpoint réservé au plan Sharp (enterprise)",
  "your_plan": "starter",
  "required_plan": "enterprise"
}

Header di quota

Ogni risposta autenticata include:

Header	Descrizione
`X-Quota-Limit`	Il tetto orario del tuo piano.
`X-Quota-Remaining`	Richieste rimanenti nell’ora UTC corrente.
`X-Quota-Cost`	Costo di questa richiesta (1).
`X-Rows`	Numero di righe restituite (informativo, se ≥ 1).
`Retry-After`	Solo sulle risposte `429`: secondi fino alla prossima ora UTC.

Superamento (429)

Esaurita la quota, le richieste restituiscono 429 fino all’azzeramento:

429

{
  "detail": "Quota de requêtes horaire dépassé",
  "quota": { "limit": 10000, "used": 10000, "period": "2026-07-22T14" }
}

L’header Retry-After indica i secondi fino all’azzeramento (inizio dell’ora successiva, UTC).

Portata istantanea: 50 richieste / secondo

Oltre alla quota oraria, ogni chiave è limitata a 50 richieste al secondo. Questo limite protegge la disponibilità del servizio: senza, un solo client potrebbe esaurire la propria quota oraria in pochi secondi e saturare l’API per tutti. Oltre tale soglia la risposta è 429 — senza consumare quota:

429

{
  "detail": "Débit maximal dépassé : 50 requêtes par seconde et par clé. Réessayez dans une seconde.",
  "limit_per_second": 50
}

L’header Retry-After vale 1: il contatore riparte al secondo successivo, a differenza della quota oraria che attende l’inizio dell’ora. In pratica, distribuisci le chiamate invece di inviare raffiche — 50 richieste al secondo bastano ampiamente per alimentare un modello in tempo reale.

Una sola connessione WebSocket per chiave

Il flusso WebSocket (/ws, piano Sharp) accetta una connessione simultanea per chiave API. Ogni socket riceve l’intero flusso: più connessioni sulla stessa chiave moltiplicano la banda senza aggiungere nulla. Una seconda connessione viene rifiutata con il codice di chiusura 4409:

4409 Une seule connexion WebSocket par clé API. Fermez la connexion existante avant d'en ouvrir une autre.

A essere rifiutata è la connessione nuova, mai quella esistente: un flusso già attivo non verrà interrotto a favore di un duplicato — tipicamente uno script riavviato senza chiudere il precedente. Se il client si è disconnesso bruscamente, il posto si libera alla chiusura del socket lato server, e riconnettersi subito funziona. Servono più flussi in parallelo? Crea una chiave per processo dalla tua area cliente.

Monitora il tuo consumo

Il consumo dell’ora corrente è mostrato anche nella tua area cliente.

Iniziare

Concetti

Quote e limiti

Accesso per piano

Header di quota

Superamento (429)

Portata istantanea: 50 richieste / secondo

Una sola connessione WebSocket per chiave

Monitora il tuo consumo

​Accesso per piano

​Header di quota

​Superamento (429)

​Portata istantanea: 50 richieste / secondo

​Una sola connessione WebSocket per chiave

​Monitora il tuo consumo

Accesso per piano

Header di quota

Superamento (429)

Portata istantanea: 50 richieste / secondo

Una sola connessione WebSocket per chiave

Monitora il tuo consumo