エラー対応

公開 API は標準の HTTP ステータスコードと JSON ボディを使用します。クライアントは「リクエスト失敗」「成功したがデータがまだない」「ノードがオフライン」を区別してください。

ステータスコード

ステータス	意味	クライアントの対応
200	成功	JSON を解析。null・空配列・新しいフィールドを受け入れる
204	CORS プリフライト成功	ボディなし
400	パラメータ欠落または不正	リクエストを修正し、そのまま再試行しない
401	トークン・セッション不正	保護エンドポイントのみ。資格情報をログに残さない
403	オリジン・権限・ポリシー拒否	正確なオリジンと範囲を確認する
404	リソース・ターゲットが存在しない	ID・有効状態・デプロイバージョンを確認する
409	前提条件と状態が競合	管理データを更新して再確認する
413	ボディ・アップロードが大きすぎる	リクエストまたは ZIP を縮小する
415	未対応の Content-Type	許可された ZIP Content-Type を使う
429	レート制限	Retry-After があれば尊重し、指数バックオフする
500–504	一時的なサーバー・上流エラー	ジッター付きで回数制限付き再試行する

再試行戦略

冪等な GET だけを上限付きで再試行します。

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')
}

空データはエラーではない

以下はすべて正常です。

• 新しい Agent がまだ報告していない：latest は null。
• ウィンドウ内に Ping がない：pings は空。
• 外部遅延ソースが鮮度ウィンドウを過ぎた：sources は空。
• ターゲットが公開アドレスを隠している：Cloudflare と外部遅延は表示されない。
• 仮想化環境でセンサーが利用不可：温度は null。

例外を投げるのではなく「データがまだありません」と表示します。warnings[] はメインペイロードは返ったが任意ソースが失敗したことを意味します。内容は保持し、非ブロッキングな通知を表示してください。逆に HTTP 200 が成功を保証するわけでもありません。Latency の互換パスは { "ok": false, "error": "..." } を返すことがあるため、ステータスと ok の両方を確認してください。

互換性のルール

v1 は任意フィールドを追加できますが、既存フィールドを黙って削除・リネームすることはありません。クライアントは api_version を確認し、未知フィールドを無視し、JSON キーの順序に依存せず、タイムスタンプを明示的にソートし、null・欠落フィールド・空配列にデフォルトを定義し、エラーテキストを innerHTML で注入しないでください。

ブラウザの CORS エラー

curl は成功するのにブラウザだけ失敗する場合、オリジンが DEVELOPER_API_ORIGINS にありません。https://status.example.com のような完全なオリジンを、パスなし・* なしで追加してください。HTTP は localhost・127.0.0.1・[::1] の開発アドレスだけ許可されます。

更新チェックの 429

更新カードが公式マニフェストの読み取りで 429 を受け取った場合、キャッシュまたは同梱マニフェストへフォールバックし、ソースを明示します。この降格状態を Agent の更新失敗と扱わず、15 分のバックオフを回避するために連続リフレッシュもしないでください。公式・キャッシュ・同梱マニフェストがすべて利用不可の場合のみ、一時的なサーバーエラーとして扱います。

診断情報を安全に収集する

記録するのは：アプリ・Agent バージョン、タイムスタンプ、メソッドとパス、HTTP ステータス、X-NIE-SLA-API-Version、X-NIE-SLA-Cache（または v1 旧別名）、サニタイズ済みの error/warnings。Authorization、x-admin-session、TOTP、導入コマンド全文、バックアップパスワード、NQ 画像ホストの URL・トークンは記録しません。