account-manager/references/ERRORS.md

终端错误码（account-manager）

约定：集成解析必须读取 stdout；多数失败后仍为单行 JSON，success=false。老旧别名路径可能出现 ERROR: 文本前缀——仍以「是否能解析 JSON」为首要判定。

机器 JSON 失败格式（常见）

{
  "success": false,
  "error": {
    "code": "……",
    "message": "……"
  }
}

部分 CLI（例如遗留 ERROR:INVALID_PLATFORM）仍可能在成功行前额外打印 hint——请以 INTEGRATION.md 的建议解析顺序为准。

---

ERROR:CLI — CLI 参数 / 路由

前缀	含义
ERROR:CLI_ADD_MISSING_ARGS	add 参数不足
ERROR:CLI_GET_MISSING_ID	get 缺少 id
ERROR:CLI_OPEN_MISSING_ID	open 缺少 id
ERROR:CLI_DELETE_MISSING_ARGS	delete 参数不足
ERROR:CLI_DELETE_BAD_MODE	delete 第二段不是 id/platform
ERROR:CLI_LIST_JSON_MISSING_PLATFORM	list-json 缺少平台参数
ERROR:CLI_PICK_WEB_MISSING_ARGS	pick-web 缺少平台
ERROR:CLI_BAD_ARGS	子命令参数缺失或非法
ERROR:CLI_UNKNOWN_OR_BAD_ARGS	无法识别的子命令或参数组合

---

ERROR: — 数据库 / 通用

前缀	含义
ERROR:DB_ERROR	SQLite 写入失败等

---

ERROR: — 平台与账号

前缀	含义
ERROR:INVALID_PLATFORM	平台名无法识别
ERROR:NO_ACCOUNTS_FOUND	列表无结果
ERROR:ACCOUNT_NOT_FOUND	指定 id 不存在
ERROR:ACCOUNT_DISABLED	账号状态为 disabled
ERROR:NO_ACCOUNT	pick-web 无符合条件的可用账号（含均被 active 未过期 lease 占用）

---

ERROR: — 租约

前缀	含义
ERROR:LEASE_CONFLICT	同账号已有 active 未过期 lease
ERROR:LEASE_NOT_FOUND	未找到活跃租约
ERROR:LEASE_EXPIRED	租约已过期

---

ERROR: — 凭据与 Secret

前缀	含义
ERROR:CREDENTIAL_NOT_FOUND	凭据不存在
ERROR:CREDENTIAL_DISABLED	凭据不可用
ERROR:SECRET_STORAGE_UNSUPPORTED	不支持的 secret 存储方式
ERROR:SECRET_REF_MISSING	env 存储缺少环境变量名
ERROR:SECRET_READ_FAILED	读取 secret 失败
ERROR:SECRET_WRITE_FAILED	写入 secret 失败
ERROR:SECRET_ENV_MISSING	环境变量未设置
ERROR:WINDOWS_CREDENTIAL_UNAVAILABLE	非 Windows 平台不支持

---

ERROR: — 浏览器 / 环境

前缀	含义
ERROR:需要 playwright Python 包	未安装 playwright 包或本机无 Chrome/Edge
ERROR:PROFILE_DIR_MISSING	账号记录中 profile_dir 为空

---

v2 新增错误码（机器可读 JSON，code 字段通常 无 ERROR: 前缀）

加密 / Master Key

错误码	触发场景
ERR_MASTER_KEY_MISSING	环境变量与 master.key 均未解析到合法密钥
ERR_MASTER_KEY_EXISTS	init-master-key 时文件已存在且未 --rotate
ERR_MASTER_KEY_INVALID	--from-env / 环境变量提供字符串无法归一成 Fernet key
ERR_CREDENTIAL_DECRYPT_FAILED	Fernet 解密失败（CredentialDecryptError，典型为密文损坏或 key 不匹配）
ERR_CREDENTIAL_NOT_ENCRYPTED	db.credentials_repo.read_credential_plaintext 对 secret_storage='none' 抛出 CredentialNotEncryptedError；CLI get-credential --reveal 会捕获并返回 plaintext: null（非致命 JSON 错误）

凭据导入导出

错误码	触发场景
ERR_EXPORT_REQUIRES_PLAINTEXT_FLAG	export-credentials 未带 --plaintext

add-web 扩参

错误码	触发场景
ERR_AUTH_STRATEGY_NOT_SUPPORTED	--auth-strategy 不在允许集合 / 账号缺少策略（同进程 dispatcher 亦使用）
ERR_INVALID_SESSION_PERSISTENT	--session-persistent 不是 0 或 1
ERR_DEVICE_FINGERPRINT_NOT_APPLICABLE	非 device_bound 策略却传入 --device-fingerprint

add-secret + local_encrypted

错误码	触发场景
ERR_LOCAL_ENCRYPTED_REQUIRES_STDIN	local_encrypted 未配合 --secret-stdin
ERR_LOCAL_ENCRYPTED_TYPE_NOT_ALLOWED	credential_type 不允许加密（如 browser_profile / note）
ERR_LOCAL_ENCRYPTED_EMPTY_STDIN	stdin 无内容

get-credential / 访问控制

错误码	触发场景
ERR_LEASE_INVALID	--reveal 时 lease 缺失、过期或不匹配账号
ERR_CREDENTIAL_MISSING	账号下无 status=active 的凭据

---

rpa_helpers（同进程异常，非 CLI）

详见 RPA_HELPERS.md。AuthStrategyError.code 取值：

错误码	触发场景
ERR_AUTH_STRATEGY_NOT_SUPPORTED	auth_strategy 为空或 dispatcher 不识别的字符串
ERR_CREDENTIAL_MISSING	策略需要 credentials["plaintext"] 但未提供
ERR_AUTH_STRATEGY_NOT_AUTOMATABLE	client_certificate
ERR_DEVICE_FINGERPRINT_MISMATCH	device_bound 机器指纹与账号不一致

---

非前缀输出提示

• pick-web / account get / account list 成功：stdout 多为单行 JSON（不一定含 success 字段）。
• 失败：优先解析 JSON；否则兼容 ERROR: 文本。