# 错误代码

本页列出 MoreLogin API 返回的常见错误代码。

## 响应格式

所有 API 响应都遵循以下标准格式：

```json
{
  "code": 0,
  "msg": null,
  "data": {},
  "requestId": "unique-request-id"
}
```

| 字段 | 类型 | 描述 |
|  --- | --- | --- |
| `code` | 整数 | `0` = 成功，`>0` = 错误 |
| `msg` | 字符串 | 错误信息（成功时为 null） |
| `data` | 对象 | 响应数据 |
| `requestId` | 字符串 | 用于故障排查的唯一请求标识符 |


## 错误码如何标识所属领域

错误码不是从一个扁平序列里分配的。每个产品领域各占一个区段，因此前两三位数字就能告诉你是哪个子系统拒绝了请求：

| 区段 | 领域 |
|  --- | --- |
| `14xxx` | 代理 |
| `15xxx` | 分组与标签 |
| `19xxx` | 浏览器环境 |
| `20xxx` | 钱包、订单与计费 |
| `21001` | 客户端版本过低 |
| `33xxx` | 云手机 |
| `35xxx` | API 认证与限流 |
| `39xxx` | 云存储 |
| `40xxx` | 云浏览器运行时 |
| `41xxx` | Webhook 配置 |
| `99xxx` | 网关与请求校验 |


每个接口都会列出它已知会返回的错误码。参见 [端点重试与完成矩阵](/zh/api-reference/getting-started/endpoint-behavior) 中按产品分类的页面。

## 常见错误代码

任何接口都可能返回，因为它们来自请求校验、权限检查与网关，而不是业务逻辑。

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `0` | 成功 | — |
| `21001` | 客户端版本过低 | 升级 MoreLogin 桌面客户端 |
| `35000` | API请求过于频繁，请稍后再试 | 对可重试的操作带抖动退避后重试；参见[限流](/zh/api-reference/getting-started/rate-limits) |
| `99000` | 系统未知错误 | 稍后重试；联系支持时请提供 `requestId` |
| `99001` | 请求参数无效 | 检查请求体格式与必填字段 |
| `99002` | 无操作权限 | 检查你的账号权限 |
| `99003` | 请求异常 | 根据 `msg` 做相应的业务调整 |
| `99004` | 请求体过大 | 减小请求体 |
| `99005` | 已有同一请求在处理中 | 等待正在处理的请求结束后再重试 |
| `99006` | 错误的请求 | 检查 HTTP 方法、请求头与请求体 |
| `99007` | 请求 IP 不在允许列表内 | 把调用方 IP 加入允许列表 |
| `99008` | IP 或设备请求次数超限 | 降低来自该 IP 或设备的请求量 |
| `99009` | 请求过于频繁 | 带抖动退避后重试 |
| `99011` | 请求时间戳已过期 | 用当前时间戳重新发送 |
| `99012` | 需要费用权限 | 使用团队所有者账号，或为成员授予费用权限 |


### 云手机（`33xxx`）

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `20002` | 原包月订单已取消 | 为符合条件的云手机重新发起包月购买 |
| `20003` | 原包月订单已退款 | 为符合条件的云手机重新发起包月购买 |
| `20004` | 原包月订单不存在 | 核对云手机购买状态；若持续出现，请携带 `requestId` 联系支持 |
| `20008` | 原包月订单未完成或状态无法确认 | 重试前先核对订单与云手机状态 |
| `20055` | 云手机不存在、已删除或不属于当前团队 | 核对每个云手机 ID 及其团队归属 |
| `20068` | 已存在待支付的包月订单 | 先完成或取消待支付订单，再调用激活接口 |
| `20070` | 云手机正在并发购买 | 等待进行中的购买完成，读取状态后再决定是否重试 |
| `20071` | 所选包月 SKU 已下架或没有有效的 30 天价格 | 重新查询包月 SKU 接口并选择可购买商品 |
| `33420` | 同一批次不能混合已购买与未购买的云手机 | 按购买状态拆分云手机后分别提交 |
| `33421` | 不能混合来自不同购买订单的已付款云手机 | 按原购买订单分别提交激活批次 |
| `33422` | 支付已成功，但激活未完成或结果尚无法确认 | 检查 `data.results` 及每台云手机的到期状态，不要盲目再次支付 |
| `33300` | 云手机不存在 | 核对云手机 ID 及其是否属于你的团队 |
| `33301` | 云手机未开机 | 先开机并等待进入可运行状态 |
| `33308` | 云手机其他成员使用中，无法关机 | 等其他成员释放后重试 |
| `33309` | 云手机其他成员使用中，无法连接 | 等其他成员释放后重试 |
| `33315` | 账户余额不足或欠费，云手机已被冻结；请充值后再使用 | 为钱包充值 |
| `33316` | 可用环境数不足，云手机已限制使用；请升级套餐后再使用 | 升级套餐 |
| `33317` | 当前环境的权限已被回收，无法启动；如需启动，请联系管理员授权 | 请管理员授予访问权限 |
| `33318` | 账户余额不足或欠费，无法启动云手机，请先充值 | 为钱包充值 |
| `33321` | 当前环境不可用 | 重试前先检查环境状态 |
| `33322` | 当前环境代理检测中 | 轮询直到检测完成 |
| `33323` | 当前环境启动中 | 等待启动完成；不要重发 |
| `33324` | 当前环境运行中 | 无需处理 |
| `33325` | 环境已停用 | 使用前先重新激活 |
| `33331` | 云手机「一键新机中」，无法关机 | 等待其完成 |
| `33332` | 云手机「重启中」，无法关机 | 等待其完成 |
| `33333` | 云手机「重置中」，无法关机 | 等待其完成 |
| `33338`–`33345` | 国家、时区、语言、经度或纬度缺失或无效 | 参见[国家与时区对照表](/zh/api-reference/appendix/country-time-zone) |
| `33346` | 商品已下架 | 改用其他 `skuId` |
| `33347` | 当前机型云手机仅支持在Windows最新版客户端上使用，请升级客户端。 | 升级 MoreLogin 桌面客户端 |
| `33367` | 系统升级维护中，暂时无法开机，恢复时间请查看系统通知或咨询客服 | 查看系统公告了解恢复时间 |
| `33376` | 按月计费已到期 | 续订订阅 |
| `33398`–`33400` | 经度、纬度或海拔超出范围 | 经度 −180…180，纬度 −90…90，海拔 −50000…100000 |
| `33401` | 该云手机暂不支持 | 使用受支持的机型 |
| `33407` | 超过并发包额度 | 等待空出并发槽位，或提升配额 |
| `33408` | 请输入正确的手机号 | 以 `+` 开头，国家代码 1–3 位（不含 86），总长 8–14 位 |
| `33418` | 直播文件不存在或已失效 | 用 `uploadType=2` 上传，并使用返回的 `fileId` |
| `33419` | 直播文件仅支持 MP4 格式 | 通过 `/cloudphone/uploadFile` 上传 MP4 |
| `33005` | 安装应用失败 | 重试；并检查设备存储空间 |
| `33014` | 操作太频繁，请稍后再试 | 退避后重试 |
| `33714` | 应用不存在或已下架 | 刷新应用库 |
| `33814` | RPA模板不存在 | 重新列出模板并使用当前的 `templateId` |
| `33818` | RPA模板参数格式错误 | 把 `templateParameter` 作为转义后的 JSON 字符串发送 |
| `33303` | 创建云手机失败 | 重试前先查询 `/cloudphone/page`；不要盲目重发 |
| `33320` | 当前环境绑定的代理已删除 | 用 `/cloudphone/setProxy` 重新绑定代理 |
| `33326` | 云手机其他成员使用中，无法一键新机 | 等其他成员释放后重试 |
| `33350` | 部分云手机“ADB开启失败”，请检查。失败原因：云手机未启动或云手机不支持ADB | 这些云手机未运行或不支持 ADB；重新读取状态后仅重试它们 |
| `33507` | 文件不存在 | 检查路径；下载请求会先扫描父目录再传输 |


安装与开关机操作还可能返回 `33001`–`33033`、`33500`–`33520`、`33700`–`33724`、`33900`–`33910` 区段内设备操作错误码。具体哪些可达取决于设备类型，因此各接口不逐一列出。

### 浏览器环境（`19xxx`）

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `19001` | 环境名称存在 | 换一个唯一的名称，或省略 `envName` 让系统生成 |
| `19002` | 创建失败 | 重试前先用 `/env/page` 确认 |
| `19004` | UA格式错误 | 发送可解析的 `advancedSetting.ua` |
| `19005` | cookie格式错误 | 把 `cookies` 作为转义后的 JSON 数组字符串发送 |
| `19039` | 环境找不到 | 核对 `envId` / `uniqueId` 及其是否属于你的团队 |
| `19063` | 您创建的环境个数已达到上限，无法继续创建 | 删除环境或升级套餐 |
| `19064` | 您没有对此分组操作的权限 | 请管理员授予该分组的访问权限 |
| `19065` | 您没有对此环境操作的权限 | 请管理员授予该环境的访问权限 |
| `19099` | 可用环境数不足，环境已限制使用，请升级套餐后再使用。 | 升级套餐 |
| `19100` | 平台ID无效 | 使用 `/system/platform/list` 返回的 `platformId` |
| `19101` | 站点ID无效 | 使用 `/system/platform/list` 返回的 `siteId` |
| `19102` | 自定义平台地址不能为空 | 当 `platformId` 为 `9999` 时必须发送 `platformUrl` |
| `19103` | 指定URL格式错误 | 在 `afterStartupConfig` 中发送合法的绝对 URL |
| `19104` | 分组ID无效 | 使用团队内已存在的分组 |
| `19105` | 标签ID无效 | 使用团队内已存在的标签 |
| `19106` | 代理ID无效 | 使用团队内已存在的代理，或省略 `proxyId` |
| `19107` | 内核版本无效 | 从 `/env/advanced/ua/versions` 中选择版本 |
| `19108` | UA版本无效 | 从 `/env/advanced/ua/versions` 中选择版本 |
| `19109` | UA版本与UA不一致 | 让 `uaVersion` 与 `advancedSetting.ua` 一致，或只传其中一个 |
| `19110` | 自定义URL格式错误 | 发送合法的绝对 URL |
| `19111` | 火狐浏览器仅支持windows、macos操作系统 | 改用 Windows 或 macOS，或切换到 Chrome |
| `19112` | 加密密钥未设置，不能开启环境加密 | 为团队配置加密密钥，或发送 `isEncrypt=0` |
| `19141` | 限制100字符，仅支持数字、字母或空格 | 缩短 `accountInfo.otpSecret` 并去掉其他字符 |
| `19142` | 暂不支持修改端对端加密环境 | 加密环境请使用 MoreLogin 客户端操作 |
| `19143` | 当前客户端客户端版本过低，无法适配内核，请升级客户端。 | 升级 MoreLogin 桌面客户端 |
| `19147` | 超出每日创建上限，若要提高每日上限数，请升级套餐。 | 升级套餐以提高上限 |
| `19149` | 请设置要清除的缓存类型 | 至少选择一类要清除的缓存 |
| `19159` | 系统类型与高级参数不匹配 | 更新时不能改操作系统；保持 `advancedSetting.os` 与已存值一致 |
| `19160` | 浏览器类型与高级参数不匹配 | 更新时不能改浏览器类型；保持 `advancedSetting.vendor` 与已存值一致 |
| `19175` | 当前经、纬度坐标不在服务范围内，请重新设置 | 选择服务范围内的坐标 |
| `19193` | 分享方已禁止编辑该环境 | 请分享方开放编辑权限 |


### 云存储（`39xxx`）

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `39001` | 网盘信息不存在 | 确认团队已开通云存储 |
| `39011` | 网盘文件不存在 | 核对文件 ID |
| `39014` | 网盘文件访问地址为空 | 重新登记该上传 |
| `39037` | 文件扩展名参数无效 | 发送受支持的扩展名 |
| `39041` | 存储空间已达上限，请清理网盘文件 | 删除文件以释放空间 |
| `39044` | 文件名重复 | 重命名该文件 |
| `39045` | 待上传预签名总量超限 | 先完成或放弃待确认的上传 |
| `39046` | 文件未成功上传 | 先把文件 PUT 到预签名 URL，再调用 complete |
| `39047` | 网盘已过期 | 续订云存储 |
| `39048` | 网盘标签不存在 | 使用 `/cloudstorage/tag/all` 返回的标签 |
| `39049` | 标签ID不能为空 | 至少发送一个标签；空列表会被拒绝 |
| `39050` | 文件名长度不能超过60个字符 | 缩短文件名 |
| `39051` | 文件大小必须大于0B且小于2GB | 拆分或压缩该文件 |


### 代理（`14xxx`）与钱包（`20xxx`）

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `14003` | 修改代理出错了 | 核对代理 ID |
| `14017` | 删除失败，所选代理不可删除 | 未过期的云平台代理无法删除；等其过期 |
| `14023` | 代理类型不存在 | 使用受支持的类型取值 |
| `14024` | 代理不存在 | 核对代理 ID |
| `14519` | 动态代理信息不能修改 | 动态代理请在代理接口之外管理 |
| `20018` | 获取商品价格失败，无法购买 | 稍后重试；联系支持时请提供 `requestId` |
| `20029` | 钱包账户异常，请联系管理员！ | 检查团队钱包是否可用 |
| `20032` | 钱包账户查询余额失败，请联系管理员！ | 稍后重试；联系支持时请提供 `requestId` |
| `20041` | 余额不足！ | 为钱包充值 |


### 云浏览器运行时（`40xxx`）

由 `/cloudbrowser/start`、`/cloudbrowser/stop` 与 `/cloudbrowser/connect` 返回。启动请求派发之后才抛出的错误码会在 `/cloudbrowser/page` 上体现，而不是在启动响应里。

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `40001` | 云浏览器运行中 | 无需处理；直接连接已有的运行 |
| `40002` | 云浏览器当前无法关闭，请刷新后重试 | 重新读取 `/cloudbrowser/page` 后重试 |
| `40003` | 检测失败！请检查代理信息是否可用 | 确认所绑代理可达 |
| `40006` | 云浏览器操作失败，请重试 | 重试；若归档失败，查看 `cloudBrowserArchiveStatus` |
| `40008` | 未找到正在运行的云浏览器 | 先启动一个，或重新读取 `/cloudbrowser/page` |
| `40009` | 无法连接其他成员启动的云浏览器 | 请该成员释放后再连接 |
| `40010` | 连接云浏览器失败，请重试 | 重试；桌面访问令牌未能签发 |
| `40015` | 当前环境未设置代理，请先设置代理 | 先用 `/env/setProxy/batch` 绑定代理 |
| `40016` | 云浏览器启动请求失败，请重试 | 重试 |
| `40020` | 云浏览器正在关闭，请稍后重试 | 等待关闭完成 |
| `40021` | 云浏览器正在启动，请勿重复操作 | 不要重发；轮询 `/cloudbrowser/page` |
| `40023` | 当前环境正在使用中，请关闭后再试 | 先关闭另一个会话 |
| `40024` | 云浏览器未能及时启动，请重新尝试 | 重新启动 |
| `40025` | 当前环境绑定的代理不存在，请重新设置代理 | 重新绑定代理 |
| `40026` | 当前环境绑定的代理已过期，请更换或续费代理 | 续费或更换代理 |
| `40027` | 当前环境绑定的代理正在分配中，请稍后重试 | 等分配完成后重试 |
| `40028` | 暂不支持本地代理，请更换代理 | 改用非本地代理 |
| `40029` | 当前代理类型暂不支持，请更换代理 | 改用受支持的代理类型 |
| `40037` | 「端对端加密」环境暂不支持使用云浏览器 | 使用未加密的环境 |


### Webhook（`41xxx`）

由 Webhook 配置接口在回调地址被拒绝时返回。

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `41001` | 回调地址必须是有效的 HTTPS 地址 | 提交不超过 1024 个字符的 HTTPS 地址，不带用户信息与片段，端口合法，并确保其解析到的每个地址都是公网可路由的 |


### API 认证（`35xxx`）与团队（`12xxx`）

| 代码 | 描述 | 解决方案 |
|  --- | --- | --- |
| `12002` | 团队不存在 | 该成员所属团队已被移除；请联系支持 |
| `35002` | API认证失败 | 检查 `client_id`（API ID）与 `client_secret`（API Key） |
| `35005` | 当前请求无操作权限 | 该成员已被停用，或调用方 IP 未通过 Open API 的允许与拒绝列表 |


## HTTP 状态码

| 状态 | 描述 |
|  --- | --- |
| `200` | 请求已处理（业务结果请看 `code` 字段） |
| `401` | 未授权——访问令牌无效或已过期 |
| `403` | 禁止访问——权限不足 |
| `429` | 请求过多——已触发限流 |
| `500` | 服务器内部错误——请联系支持 |


当前应用网关用业务码 `35000` 表示自身的限流拒绝，并不会显式设置 HTTP `429`。边缘代理或未来版本的网关仍可能返回 `429`，因此客户端应同时处理两种形式。

## 重试与恢复语义

| 失败类别 | 可否重试 | 客户端必须的行为 |
|  --- | --- | --- |
| 校验、权限、余额或功能不支持类错误 | 不可 | 先修正请求、权限、余额或所选资源，再重试 |
| 限流（`35000`） | 可，有条件 | 带抖动退避；即使 HTTP 状态是 `200` 也要检查响应体 `code` |
| 服务临时故障 | 可，有条件 | 读操作可重试；写操作先查询资源或任务状态 |
| 异步操作已受理 | 不要立即重发 | 轮询文档指定的状态接口，直到成功、失败或超时 |
| 网络超时后结果未知 | 先做状态检查 | 不要盲目重复创建、购买、上传登记或计划创建 |


本公开 API 目前没有通用的幂等键请求头。因此对于会改变状态的请求，按接口查询状态是安全恢复的一部分。

对于异步操作，`code: 0` 的响应可能表示「已受理」而非「已完成」。请按该接口文档说明的状态字段与终态判断。

全部接口见 [端点重试与完成矩阵](/zh/api-reference/getting-started/endpoint-behavior)，轮询流程与终态见 [异步操作](/zh/api-reference/getting-started/async-operations)。

> **提示**：联系支持时请始终附上响应中的 `requestId`，以便更快排查。