Quote e limiti di frequenza

L'API FreeMaint impone una quota giornaliera per azienda, reimpostata a mezzanotte UTC. Il limite dipende dal tuo livello; i contatori e i rimanenti vengono esposti come intestazioni di risposta.

Tappi giornalieri

• Core, Starter — 0 (una chiave API richiede Business)
• Business — 5.000 chiamate/giorno (GraphQL e l'endpoint di ingest energia condividono lo stesso contatore)
• Enterprise — 100.000 chiamate/giorno
• On-Premise — illimitato (limite = null)

Intestazioni di risposta

• X-RateLimit-Limit: il limite giornaliero del tuo livello
• X-RateLimit-Remaining: chiamate rimaste oggi (diminuisce per ogni chiamata conteggiata nella quota)
• X-RateLimit-Reset: timestamp Unix di mezzanotte UTC (prossimo ripristino)

Ciò che non conta

Solo /public-api/whoami è gratuito: non decrementa il contatore, così puoi verificare una chiave e il suo piano senza consumare quota. Tutto ciò che passa da /api/v1/graphql viene conteggiato, inclusa la query whoami, e lo stesso vale per l'endpoint di ingest energia.

Che cosa conta come una chiamata

Il contatore aumenta per OPERAZIONE, non per richiesta HTTP. Raggruppare 50 mutazioni con alias in un'unica richiesta consuma comunque 50 unità. Raggruppare fa risparmiare viaggi di rete, mai quota. Per rendere sostenibile una sincronizzazione ricorrente, richiedete solo ciò che è cambiato con parts(updatedSince: "...") invece di rileggere l'intero catalogo.

Quando superi il limite

Una volta raggiunto il limite giornaliero, ogni ulteriore chiamata viene rifiutata con il messaggio «Daily API cap reached». Sulle superfici REST (/public-api/ping, l'endpoint di ingest energia) è un HTTP 403. Su GraphQL lo stato HTTP è 200 e il rifiuto si trova in errors[0].extensions.code = FORBIDDEN, con originalError.statusCode = 403. Il contatore riparte alle 00:00 UTC. Non esiste un limite morbido, né una tolleranza di burst, né una finestra al minuto: la finestra è la giornata.