认证、错误与请求约定
基址与路径
公网接口统一由 /cm/ 反向代理到后端；自有章节使用 /cm/auth/... 等完整路径。网易云泛化接口是 /cm/ncm/<上游路径>。/developer、/station 与文档站是网页入口，不是账号 API。
同一个路径可能有多个 HTTP 方法，必须按方法分别接入。除非明确是查询，不要用 GET 发起写操作；JSON 写入请求设置 Content-Type: application/json。GET 无请求体时不需要这个请求头。
两套令牌不可混用
| 凭据 | 取得方式 | 用途 |
|---|---|---|
| CurrentMusic 会话 token | /cm/auth/login 等账号登录接口 | 音乐客户端账户、绑定、社区、管理等服务 |
| 通行证 access_token | /cm/passport/token 授权码 / 刷新令牌 / 客户端凭据流程 | 被 scope 授权的第三方产品能力；以通行证专题为准 |
| 网易云 Cookie | 仅由服务端管理的绑定流程产生 | 客户端不能直接传入泛化网关覆盖登录态 |
通常使用 Authorization: Bearer <token>。401 可能是会话失效，也可能是网易云尚未绑定或上游绑定已失效，必须结合响应文案判断，不能一律删除本地账号。
账户退出、设备下线、密码找回等操作会影响已发出的会话和通行证授权；细节见密码协议与通行证。管理员接口还会检查角色与目标账号等级，持有普通会话不代表有管理权限。
登录设备与会话
同一账号的登录设备数量不限；新设备登录不会自动淘汰已有设备，也不会因设备数量撤销已有通行证授权。App 与网页会话均可通过以下接口管理：
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /cm/auth/sessions | 返回 { "max": null, "sessions": [...] }；max: null 表示无数量上限，sessions 为完整设备列表 |
| DELETE | /cm/auth/sessions/{id} | 下线指定设备，并撤销该会话发出的通行证授权 |
| DELETE | /cm/auth/sessions/others | 保留当前设备，下线其他设备；返回 removed 数量 |
设备数严格超过 5 台时，设备管理界面显示账号安全风险提示，建议核对并退出不认识或不再使用的设备；提示不限制登录。设备降至 5 台及以下后取消提示。密码重置、登录保护变更、主动退出与管理员下线仍按各自规则撤销会话。
网易云泛化网关
| 等级 | 登录态 | 缓存与写入 |
|---|---|---|
| T0 | 通常公开只读；媒体地址族仍强制 CurrentMusic 登录 | GET 按登记 TTL 缓存；专用封装优先 |
| T1 | CurrentMusic 登录 + 有效网易云绑定 | 账号态只读，不共享用户缓存 |
| T2 | CurrentMusic 登录 + 有效网易云绑定 + confirm: true 或 confirm=1 | 写操作留审计，推荐 POST，按接口传参数 |
| T3 | 禁止泛化转发 | 返回 403，必须使用项目专用的登录、绑定等入口 |
只放行登记表内且已启用阶段的路径。媒体地址族包括 /song/url、/song/download/url、/mv/url、/video/url、/song/cloud/download、/voice/detail 等，以登记表与实现为准。
cookie、token、realIP、randomCNIP、confirm、file 是网关保留字段，不会作为普通业务参数原样转发。confirm 用于本站二次确认，file 用于专用上传；真实 IP 由可信反向代理处理，不接受客户端伪造。
上传使用 JSON base64 通道，仅白名单路径支持。字段 file、filename、contentType，解码后最多 3 MiB；不要把二进制或 base64 塞到 URL 查询串。聊天图片与头像等专用接口有各自更严格的限制。
错误与限流
自有接口常用错误格式：
{"error": "错误说明"}
通行证使用 OAuth 的 error / error_description。网易云泛化响应保留上游业务字段，应同时检查 HTTP 状态及上游业务码，不能把 code 当作所有自有接口共有字段。
| HTTP | 常见含义 | 客户端处理 |
|---|---|---|
| 400 | 参数缺失、范围错误、未确认写入 | 修正输入，不盲目重试 |
| 401 | 未登录、会话失效、缺少绑定 | 按错误说明引导账号登录或重新绑定 |
| 403 | 权限不足、T3 泛化禁止、业务限制 | 改用正确权限或专用接口 |
| 404 | 路径不存在、对象不存在、登记阶段未启用 | 核对路径和资源 |
| 409 | 名称/账户等冲突 | 根据业务修正 |
| 429 | 请求过频或验证码配额耗尽 | 退避并遵守文案中的冷却时间 |
| 502/503 | 上游失败或熔断 | 有上限地退避重试，避免并发重试风暴 |
后端通用频控为每 IP 每分钟 300 次，认证入口另设每 IP 每分钟 30 次；验证码、聊天和代理层可能有更严格限额。反向代理和 CDN 也可能先返回 HTML 错误页；解析 JSON 失败时先检查状态与 Content-Type。
时间、分页与缓存
不要假定所有数字时间相同：账号与公告的 Unix 时间常用秒，播放位置和歌词轴用毫秒，具体以字段专题为准。分页通常使用 limit / offset，默认值和上限逐接口不同，见对应参数与校验表。get 的默认值不等于字段一定可省略。
播放直链、二维码、授权码、刷新令牌均具有生命周期，不能长期当作稳定 URL 或凭据保存。服务端的业务缓存与浏览器/CDN HTTP 缓存是两回事。
SSE 与文件
聊天 /cm/chat/live?sse=1 使用 SSE；Nginx 的公开流别名 /cm/live/chat 也转发到同一处理器。AI /cm/ai/live 为 POST SSE，也可使用已配置的 /cm/live/ai 入口。听歌房事件有房间权限和独立时间轴，见专题。生产反向代理需关闭 SSE buffering；不要用 response.json() 读取整个事件流。
分享图、头像、聊天图片、APK、投屏音频是文件响应；音频可能使用 Range/HEAD。接口中返回的资源 URL、签名 URL 和 token 含义不同，不能互换。