Protocol: Errors

所有错误码定义。命名规则:E_<CATEGORY>_<SPECIFIC> 或 W_<CATEGORY>_<SPECIFIC>(警告)。

常用错误码(节选)

这是常见子集。完整 ~32 个错误码 + 2 个警告码的权威定义见 packages/protocol/src/errors.ts 的 ERROR_META;category / retryable 一律由该表推导,不接受调用方传入。

Code	Category	Retryable	说明
E_MANIFEST_FETCH	manifest	✅	manifest 拉取失败
E_MANIFEST_PARSE	manifest	❌	manifest 解析失败
E_NETWORK	network	✅	网络错误
E_NETWORK_TIMEOUT	network	✅	网络超时
E_NETWORK_CORS	network	❌	CORS 被拦
E_AUTH_EXPIRED	auth	❌	签名 URL 过期(不做刷新,ADR-022)
E_AUTOPLAY_BLOCKED	autoplay	❌	浏览器拒绝自动播放
E_MEDIA_NOT_SUPPORTED	media	❌	浏览器不支持此格式
E_MEDIA_DECODE	media	✅	解码错误
E_METHOD_NOT_SUPPORTED	env	❌	命令当前平台不支持(如运行时换内核)
E_UNKNOWN	env	❌	其他

iframe 传输层(frame-core / embed-app 握手与连接):

Code	Category	Retryable	说明
E_HANDSHAKE_TIMEOUT	network	✅	握手超时
E_HANDSHAKE_VERSION_MISMATCH	env	❌	契约版本不兼容
E_CONNECTION_LOST	network	✅	通信断线(自动重连中)
E_LOAD_FAILED / E_LOAD_TIMEOUT	network	✅	iframe 加载失败 / 超时
E_RECONNECT_FAILED	network	✅	重连用尽仍失败

警告码(W_*,不中断播放):W_BROWSER_INCOMPATIBLE(UC / 夸克)、W_VERSION_MISMATCH。

PlayerError 结构

interface PlayerError {
  code: ErrorCode          // E_* 枚举(非自由字符串)
  message: string
  retryable: boolean       // 从 ERROR_META 推导,不由调用方传
  category: 'manifest' | 'media' | 'network' | 'auth' | 'env' | 'autoplay'
  cause?: unknown          // 原始错误(debug 用)
}

详细说明

权威来源:packages/protocol/src/errors.ts。另见 USER-GUIDE.md § 29 完整错误码表 + 用户建议。