Gestion des erreurs

L'API publique utilise les codes HTTP standard et des corps JSON. Les clients doivent distinguer « requête échouée », « réussie mais pas encore de données » et « nœud hors ligne ».

Codes de statut

Statut	Signification	Traitement côté client
200	succès	analyser le JSON ; accepter null, les tableaux vides et les nouveaux champs
204	préflight CORS réussi	pas de corps
400	paramètre manquant ou invalide	corriger la requête, ne pas réessayer telle quelle
401	jeton/session invalide	endpoints protégés uniquement ; ne jamais journaliser les identifiants
403	origine, permission ou politique refusée	vérifier l'origine exacte et le périmètre
404	ressource ou cible absente	vérifier l'ID, l'état activé, la version du déploiement
409	conflit d'état avec une précondition	rafraîchir les données admin et re-confirmer
413	corps ou téléversement trop grand	réduire la requête ou le ZIP
415	Content-Type non pris en charge	utiliser le Content-Type ZIP autorisé
429	limite de débit atteinte	respecter Retry-After si présent, reculer exponentiellement
500–504	erreur serveur/amont transitoire	réessayer un nombre borné de fois avec jitter

Stratégie de nouvelle tentative

Ne réessayez que les GET idempotents, avec une limite :

async function getJson(url, attempts = 3) {
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    const response = await fetch(url, { credentials: 'omit' })
    if (response.ok) return response.json()

    if (![429, 500, 502, 503, 504].includes(response.status)) {
      throw new Error(`Request rejected: HTTP ${response.status}`)
    }

    const retryAfter = Number(response.headers.get('retry-after') || 0) * 1000
    const backoff = Math.max(retryAfter, 500 * (2 ** attempt))
    const jitter = Math.floor(Math.random() * 250)
    await new Promise(resolve => setTimeout(resolve, backoff + jitter))
  }
  throw new Error('API temporarily unavailable')
}

Des données vides ne sont pas une erreur

Tout ceci est normal :

• Un nouvel Agent n'a pas encore rapporté : latest vaut null.
• Aucun ping dans la fenêtre : pings est vide.
• Les sources de latence externe ont dépassé la fenêtre de fraîcheur : sources est vide.
• La cible masque son adresse publique : Cloudflare et la latence externe ne sont pas affichées.
• Capteurs indisponibles en virtualisation : la température vaut null.

Affichez « pas encore de données » au lieu de lever une erreur. warnings[] signifie que le corps principal est revenu mais qu'une source optionnelle a échoué ; conservez le contenu et affichez un avis non bloquant. Inversement, un HTTP 200 ne garantit pas le succès : le chemin de compatibilité latency peut renvoyer { "ok": false, "error": "..." }, donc vérifiez à la fois le statut et ok.

Règles de compatibilité

v1 peut ajouter des champs optionnels mais ne supprime ni ne renomme jamais silencieusement les champs existants. Les clients doivent : vérifier api_version ; ignorer les champs inconnus ; ne pas dépendre de l'ordre des clés JSON ; trier les horodatages explicitement ; définir des valeurs par défaut pour null, les champs manquants et les tableaux vides ; ne jamais injecter de texte d'erreur via innerHTML.

Échecs CORS dans le navigateur

Si curl fonctionne mais pas le navigateur, l'origine manque dans DEVELOPER_API_ORIGINS. La liste d'autorisation exige des origines complètes comme https://status.example.com, sans chemin et sans *. HTTP n'est autorisé que pour les adresses de développement localhost, 127.0.0.1 et [::1].

429 sur la vérification de mise à jour

Quand la carte de mise à jour reçoit un 429 en lisant le manifest officiel, elle retombe sur un cache ou le manifest embarqué et marque la source. Ne traitez pas l'état dégradé comme un échec de mise à jour Agent et ne martelez pas le rafraîchissement pour contourner le backoff de 15 minutes. Traitez-le comme une erreur serveur transitoire uniquement si les manifest officiel, cache et embarqué sont tous indisponibles.

Collecter des diagnostics sans risque

Consignez : version application/Agent, horodatage, méthode et chemin, statut HTTP, X-NIE-SLA-API-Version, X-NIE-SLA-Cache (ou les alias v1) et error/warnings assainis. Ne consignez jamais : Authorization, x-admin-session, TOTP, commandes d'installation Agent complètes, mots de passe de sauvegarde, ni URL/jetons d'hébergeur d'images NQ.