Limiti, errori e supporto

Quante richieste puoi fare, come scrivere un'integrazione che regge nel tempo, cosa significano gli errori e a chi rivolgerti.

Limiti

2 000 richieste al giorno e 60 al minuto per client; limiti superiori su accordo dedicato.

Una chiamata bulk conta come una richiesta, qualunque sia il numero di impianti nella pagina. Una pagina bulk contiene al massimo 100 impianti.

Buone pratiche

• Tieni il token in cache per tutta la sua ora di validità; non chiederne uno per chiamata.
• Usa gli endpoint bulk per le letture periodiche di più impianti.
• Pagina con il cursore: ripassa pagination.next_cursor come cursor finché has_more è false. Tratta il cursore come un valore opaco.
• Attendi e ritenta su 429 e 503 con backoff esponenziale (per esempio 1 s, 2 s, 4 s, fino a un minuto), aggiungendo un ritardo casuale (jitter).
• 404 significa non visibile: l'impianto non esiste o non è collegato alla tua organizzazione. L'API non distingue i due casi.
• Tollera i campi nuovi: ignora i campi che non conosci; possono essere aggiunti all'interno di /v1.
• null è un valore: gestisci potenze, stati di carica ed energie null.

Errori

Ogni errore dell'API restituisce lo stesso formato JSON:

{
  "error": {
    "code": "PLANT_NOT_FOUND",
    "message": "Plant 7b0728a9-853c-4b31-8446-a4eb00607566 not found",
    "request_id": "req_21ee1d5946a8",
    "details": {}
  }
}

Gli errori dell'endpoint del token seguono invece il formato OAuth 2.0 ({"error": "invalid_client"}).

Codice	HTTP	Significato	Cosa fare
INVALID_TOKEN	401	token mancante, malformato o non valido	ottieni un nuovo token
TOKEN_EXPIRED	401	token scaduto	ottieni un nuovo token
INVALID_AUDIENCE	401	token non emesso per questa API	usa le credenziali del tuo client API
AUTHENTICATION_FAILED	401	autenticazione fallita	ottieni un nuovo token
SCOPE_REQUIRED	403	il client non ha lo scope richiesto	contatta zeroCO2
PLANT_NOT_FOUND	404	impianto sconosciuto o non visibile al client	verifica l'id con GET /v1/plants
INVALID_QUERY_PARAM	400	parametro mancante o non valido	correggi la richiesta; details indica il parametro
RATE_LIMIT_EXCEEDED	429	limite di richieste raggiunto	attendi e ritenta
SERVICE_UNAVAILABLE	503	indisponibilità temporanea	attendi e ritenta
JWKS_UNAVAILABLE	503	il token non ha potuto essere verificato	attendi e ritenta
INTERNAL_ERROR	500	errore imprevisto	ritenta una volta, poi contatta l'assistenza

Un 429 o un 5xx può occasionalmente arrivare senza questo formato: basati sempre sul codice di stato HTTP.

Versioni

La versione dell'API fa parte del percorso (/v1). All'interno di una versione le modifiche sono retrocompatibili: possono arrivare nuovi endpoint, nuovi parametri facoltativi e nuovi campi nelle risposte. Le modifiche incompatibili vengono pubblicate in una nuova versione (/v2) e la precedente resta disponibile per un periodo di transizione annunciato in anticipo.

Assistenza

Email: info@energysynt.com · Telefono: +39 049 5017583

Nella richiesta indica il request_id della chiamata fallita, l'endpoint e l'orario della richiesta (UTC).