Paginazione, errori e limiti
Scorrere un elenco lungo, leggere un codice di errore, restare sotto il limite di frequenza.
Formato delle risposte
Tutte le risposte sono in JSON. Una risposta riuscita ha questo aspetto:
{ "data": [ … ], "meta": { "limit": 100, "next_cursor": "eyJpZCI6MTIzNH0" } }e un errore questo:
{ "error": "forbidden", "message": "Portée requise : read:flows", "scope": "read:flows" }Il testo di message è in francese; per un controllo automatico basatevi su error e scope.
Le date sono in UTC nel formato ISO 8601 (2026-10-07T08:12:40Z), sia nei parametri sia nelle risposte.
Paginazione a cursore
Gli elenchi lunghi (postazioni, flussi, eventi…) arrivano a pagine. Chiamate la rotta con limit; il valore predefinito e il massimo di ogni rotta sono nel riferimento. Finché meta.next_cursor non è null, richiamate la stessa rotta, con gli stessi filtri, aggiungendo cursor=<valore>. Quando meta.next_cursor vale null, avete tutto.
curl -s "https://console.esempio.it/api/v1/flows?machine=postazione-009&period=24h&limit=500&cursor=eyJpZCI6MTIzNH0" \
-H "Authorization: Bearer $FIRSTSI_TOKEN"Il cursore è opaco: non provate a costruirlo e non cambiate i filtri da una pagina all'altra.
Periodi
Le rotte che leggono uno storico accettano o period, una finestra che termina adesso (1h, 3h, 6h, 12h, 24h, 3d, 7d, 30d), o from e to in ISO 8601. Se sono presenti from e to, period viene ignorato.
I flussi dettagliati (/flows) sono limitati a 7 giorni. Oltre, la risposta viene ridotta agli ultimi 7 giorni e meta.window_capped vale true. Per un mese intero usate /flows/destinations, /flows/summary o /flows/talkers, che leggono aggregati orari.
Codici di risposta
| Codice | Significato | Che cosa fare |
|---|---|---|
200 | Risposta normale | |
202 | Azione accettata (diagnostica NetDiag) | Il risultato arriverà negli eventi della postazione |
400 | Parametro non valido | Leggere message e correggere la richiesta |
401 | Token assente, sconosciuto, scaduto o revocato | Verificare l'intestazione Authorization, ricreare il token se serve |
403 | Ambito mancante nel token | Creare un token con l'ambito, vedi Ambiti |
404 | Elemento sconosciuto nel vostro cliente | Verificare l'identificativo o il nome host esatto |
429 | Limite di frequenza superato | Attendere i secondi indicati da Retry-After |
5xx | Errore del server | Riprovare più tardi; se persiste, contattare il supporto |
Limite di frequenza
Ogni token ha diritto a 600 chiamate al minuto. Ogni risposta riporta le intestazioni X-RateLimit-Limit e X-RateLimit-Remaining. Oltre il limite il server risponde 429 con Retry-After, in secondi.
A un'integrazione che interroga spesso conviene preferire le rotte aggregate (/flows/summary, /netdiag/machines) agli elenchi dettagliati e tenere in cache ciò che cambia poco, come l'inventario o l'elenco delle postazioni. Dopo un 429, distanziate i tentativi invece di ripeterli in ciclo.
Fonte: · Docs FirstSI · aggiornato il 10/10/2026