通用鉴权与错误
访问权限、操作受理与结果解释以 API 合同为准。
鉴权与调用约定
云机基础 Core HTTP API，供可信服务端、管理员工作台及受限业务会话调用。字段使用 snake_case；资源 ID 使用字符串；时间使用 UTC RFC3339。
默认鉴权：每次请求同时发送 X-Core-Key 和 X-Core-Secret。普通业务接口也允许 Authorization: Bearer <受限会话令牌>，两种方式互斥，不能混用。x-core-public 表示允许受限业务会话使用，并不表示匿名开放。服务凭据与会话管理接口只接受 Key/Secret；健康检查不需要凭据，文件传输链接使用自身短期票据。
状态读取约定：云机 status 是容器状态，wifi_status 是网络观测状态；只有两者都为 running 才可展示运行可用。常见设备值为 created / running，离线、缺少观测或其他 provider 的状态请按字段说明处理。
设备动作是异步任务：HTTP 202 仅表示 Core 已持久受理，后续查询 task_id；按 items[] 读取逐目标结果。任务成功不自动等于云机已联网、可投屏或备份已交付，须结合动作 result、observation 与文件 ready 状态判断。结果未知时查询原任务或按原 Idempotency-Key 查询，不自动以新键重复写入设备。Core 设备操作始终经登记机房执行。
X-Core-Key
默认服务鉴权的 Key。必须与 X-Core-Secret 同时提供，用于可信服务端或管理员独立工作台；不能与 Bearer 混用。
X-Core-Secret
默认服务鉴权的 Secret。必须与 X-Core-Key 同时提供；不要写入公开源码、URL 或普通业务用户的前端配置。
bearer
可选的受限 opaque access token，由可信服务端使用 Key/Secret 创建，限制云卡、权限及期限。普通业务接口可使用；管理接口不接受。不能同时发送服务 Key/Secret。
公共错误字段
统一错误响应。status 表示 HTTP 错误码，不是云机或任务状态；调用方按 code 分支，detail 可用于提示，request_id 用于关联日志。
| 字段 | 功能说明 |
|---|---|
type | Problem 类型标识（URI）；用于描述错误类别。 |
title | 错误类型的简短标题。 |
status | 本次错误响应的 HTTP 状态码，例如 401=未认证、403=无权限、404=不存在、409=版本或资源冲突、422=参数/业务前置条件不满足、5xx=服务端或依赖故障。不是云机状态或任务状态。 |
code | 稳定机器可读错误码，用于程序判断；这是开放字符串，新增错误码不应导致客户端崩溃。 |
detail | 本次错误的具体解释；可用于辅助提示，不作为稳定逻辑判断依据。 |
request_id | 本次 HTTP 请求的关联 ID，供日志排查；不是任务 ID 或幂等键。 |
errors | 可选的结构化错误补充，不同错误码内容不同。 |
invalid_params | 可定位到字段的参数校验错误列表，供表单就近展示。 |