错误处理

公开 API 使用标准 HTTP 状态码与 JSON 响应。客户端应区分“请求失败”“成功但暂时没有数据”与“节点已经离线”。

状态码

状态	含义	客户端处理
200	请求成功	解析 JSON，接受 null、空数组与新增字段
204	CORS 预检成功	不读取响应体
400	缺少参数或参数无效	修正请求，不要原样重试
401	Token 或 Session 无效	仅适用于受保护接口；不记录凭据
403	Origin、权限或安全策略拒绝	检查精确 Origin 与权限范围
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 为空。
• 外部 Latency 节点已过 stale 窗口，sources 为空。
• 目标启用了隐藏公网地址，Cloudflare 与外部 Latency 不对外展示。
• 虚拟化环境中传感器缺失，温度为 null。

UI 显示“暂无数据”或“尚未上报”，不要渲染成异常。warnings[] 表示主体数据已返回但某个可选来源读取失败，界面保留成功内容并显示非阻断提示。反过来，HTTP 200 不必然成功：Latency 兼容实现可能返回 { "ok": false, "error": "..." }，客户端必须同时检查 HTTP 状态与 JSON ok。

兼容性要求

v1 可以增加可选字段，但不会静默删除或重命名既有字段。客户端应：检查 api_version；忽略未知字段；不依赖 JSON 属性顺序；对时间戳显式排序；对 null、缺失字段与空数组提供默认行为；不把错误消息直接插入 innerHTML。

浏览器 CORS 报错

命令行请求成功但浏览器失败，通常是 Origin 未加入 DEVELOPER_API_ORIGINS。白名单必须是完整 Origin，如 https://status.example.com，不能包含路径，不能使用 *。HTTP 只允许 localhost、127.0.0.1 与 [::1] 开发地址。

更新检查 429

系统更新卡片读取官方 manifest 遇到 429 时，会使用缓存或随部署清单并标记来源。不要把降级状态误判为 Agent 更新失败，也不要高频刷新绕过十五分钟失败退避。官方、缓存与 bundled manifest 都不可用时，才按服务端暂时异常处理。

安全地收集排障信息

可以记录：应用/Agent 版本、发生时间、请求方法与路径、HTTP 状态、X-NIE-SLA-API-Version、X-NIE-SLA-Cache（或 v1 旧别名）与脱敏后的 error/warnings。禁止记录：Authorization、x-admin-session、TOTP、完整 Agent 部署命令、备份密码、NQ 图床地址或 Token。