Pagination, erreurs et limites
Parcourir une longue liste, lire un code d'erreur, rester sous la limite de débit.
Format des réponses
Toutes les réponses sont en JSON. Un succès ressemble à ceci :
{ "data": [ … ], "meta": { "limit": 100, "next_cursor": "eyJpZCI6MTIzNH0" } }et une erreur à cela :
{ "error": "forbidden", "message": "Portée requise : read:flows", "scope": "read:flows" }Les dates sont en UTC au format ISO 8601 (2026-10-07T08:12:40Z), dans les paramètres comme dans les réponses.
Pagination par curseur
Les longues listes (postes, flux, événements…) arrivent par pages. Appelez la route avec limit ; la valeur par défaut et le maximum de chaque route sont dans la référence. Tant que meta.next_cursor n'est pas null, rappelez la même route, avec les mêmes filtres, en ajoutant cursor=<valeur>. Quand meta.next_cursor vaut null, vous avez tout.
curl -s "https://console.exemple.fr/api/v1/flows?machine=poste-009&period=24h&limit=500&cursor=eyJpZCI6MTIzNH0" \
-H "Authorization: Bearer $FIRSTSI_TOKEN"Le curseur est opaque : ne cherchez pas à le fabriquer, et ne changez pas les filtres d'une page à l'autre.
Périodes
Les routes qui lisent un historique acceptent soit period, une fenêtre qui se termine maintenant (1h, 3h, 6h, 12h, 24h, 3d, 7d, 30d), soit from et to en ISO 8601. Si from et to sont fournis, period est ignoré.
Les flux détaillés (/flows) sont limités à 7 jours. Au-delà, la réponse est ramenée aux 7 derniers jours et meta.window_capped vaut true. Pour un mois entier, utilisez /flows/destinations, /flows/summary ou /flows/talkers, qui lisent des cumuls horaires.
Codes de réponse
| Code | Signification | Que faire |
|---|---|---|
200 | Réponse normale | |
202 | Action acceptée (diagnostic NetDiag) | Le résultat arrivera dans les événements du poste |
400 | Paramètre invalide | Lire message et corriger la requête |
401 | Jeton absent, inconnu, expiré ou révoqué | Vérifier l'en-tête Authorization, recréer le jeton si besoin |
403 | Portée absente du jeton | Créer un jeton qui a la portée, voir Portées |
404 | Élément inconnu dans votre client | Vérifier l'identifiant ou le nom d'hôte exact |
429 | Débit dépassé | Attendre le nombre de secondes donné par Retry-After |
5xx | Erreur du serveur | Réessayer plus tard ; si ça dure, contacter le support |
Débit
Chaque jeton a droit à 600 appels par minute. Chaque réponse porte les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining. Au-delà de la limite, le serveur répond 429 avec Retry-After, en secondes.
Une intégration qui interroge souvent a intérêt à préférer les routes agrégées (/flows/summary, /netdiag/machines) aux listes détaillées, et à garder en cache ce qui change peu, comme l'inventaire ou la liste des postes. Après un 429, espacez les relances au lieu de boucler.
Source : · Docs FirstSI · mis à jour le 10/10/2026