151 lines
5.2 KiB
Markdown
151 lines
5.2 KiB
Markdown
# 终端错误码（account-manager）
|
||
|
||
约定：**集成解析必须读取 stdout**；多数失败后仍为单行 JSON，`success=false`。老旧别名路径可能出现 **`ERROR:` 文本前缀**——仍以「是否能解析 JSON」为首要判定。
|
||
|
||
## 机器 JSON 失败格式（常见）
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "……",
|
||
"message": "……"
|
||
}
|
||
}
|
||
```
|
||
|
||
部分 CLI（例如遗留 `ERROR:INVALID_PLATFORM`）仍可能在成功行前额外打印 hint——请以 [`INTEGRATION.md`](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`](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:` 文本。
|