本文汇总 Agent Runtime 当前公开错误码的处理要点，帮助您区分请求参数问题、权限问题、资源状态冲突和平台侧故障，并选择合适的排查或重试动作。
如果您收到本文未列出的错误码，请保留
RequestId 并按系统错误处理，不要根据错误码前缀自行推断其含义。开始排查前先判断入口
Agent Runtime 的不同入口会暴露不同的错误信号，请先确认您看到的是哪一层：
直接调用 Cloud API 时，接口遵循腾讯云 API V3 风格，HTTP 传输状态通常仍为
200，错误详情位于 Response.Error。通过
agr CLI 调用时，除了 Cloud API 返回的错误码，还可能先遇到本地校验或凭证错误。此时请同时关注进程退出码、Failure.Code 和 Failure.Message。{"Response": {"Error": {"Code": "ResourceNotFound.SandboxInstance","Message": "sandbox instance not found"},"RequestId": "6f6e8d8b5b774e329c2f41f6e45c2f9f"}}
注意：
下表中的“错误分类”列使用 HTTP 状态码表示错误码的分类语义（如 400 表示参数类、403 表示权限类、404 表示资源不存在类、500 表示系统类），帮助您快速区分错误类型和选择处理方式。这不代表当前 Cloud API 实际返回的 HTTP 状态码——直接调用 Cloud API V3 时，传输层通常仍返回 HTTP
200，错误详情位于 Response.Error，请以该字段为准。InternalError.*、FailedOperation、FailedOperation.DeleteFailed、FailedOperation.CLSServiceError、ResourceUnavailable.Provider 等系统类错误，对外 Message 可能被脱敏为 Internal server error。遇到此类情况，请优先保留 RequestId。CLI 优先排查路径
如果您通过
agr CLI 调用 Agent Runtime，建议先按“本地配置 → 命令面 → 资源定位”的顺序排查。以下命令均为只读操作，不会修改任何资源状态；其中 tool list、tool get、instance list、instance get 需要已配置云凭证。1. 检查本地凭证、区域和默认域名配置。
agr status -o json --non-interactive
重点检查
Auth.SecretId.Present、Auth.SecretKey.Present、Region 和 Domain 字段；如果前两项为 false，请先补齐凭证。2. 运行本地诊断，排除凭证缺失场景。
agr doctor -o json --non-interactive
如果
SecretId、SecretKey 或 Connectivity 返回 warning，请先完成凭证配置，再继续执行需要访问 Cloud API 的命令。3. 如果需要确认 CLI 退出码含义：
agr explain exit-codes -o json
常见退出码如下：
退出码 | 含义 | 建议 |
0 | success | 命令执行成功。 |
1 | error | 查看 Failure.Code 或 Response.Error.Code。 |
2 | usage | 命令名、子命令或参数组合不正确；先运行 agr --help 或 agr schema -o json。 |
4 | auth | 缺少凭证或鉴权失败；先执行 agr doctor -o json --non-interactive。 |
255 | remote_execution_failed | 远端执行失败；结合 Failure.Message、实例状态和 RequestId 继续排查。 |
4. 如果已经拿到错误码，可用 CLI 内置解释辅助判断：
agr explain <error-code> -o json
5. 有凭证后，先确认 Tool 和 Instance 是否存在，再排查配额、状态或网络问题。
agr tool list --limit 20 -o json --non-interactiveagr tool get <tool-id> -o json --non-interactiveagr instance list --tool-id <tool-id> -o json --non-interactiveagr instance get <instance-id> -o json --non-interactive
如果在未配置凭证时直接执行
agr tool list -o json --non-interactive，CLI 会返回 Failure.Code=MISSING_CLOUD_CREDENTIALS 并以退出码 4 结束。此类错误发生在请求发出之前，不属于 Cloud API 的 Response.Error.Code。错误码列表
参数格式与必填项
错误码 | 错误分类 | 含义 | 诊断 | 修复方案 |
InvalidParameter | 400 | 请求格式不符合接口要求。 | 检查请求体结构、字段类型和字段组合。 | 修正请求格式后重新发起请求。 |
InvalidParameterValue | 400 | 参数值不合法，但没有命中更细分的子错误码。 | 检查字段取值范围、枚举值和格式。 | 按接口要求修改参数值。 |
MissingParameter | 400 | 缺少必填参数，但没有命中更细分的子错误码。 | 对照接口参数确认是否缺少必填字段。 | 补齐必填字段。 |
UnknownParameter | 400 | 请求中包含未知参数，或 Action 不存在。 | 检查 Action、字段名和大小写。 | 删除无效字段，或改为受支持的 Action。 |
InvalidParameterValue.ToolType | 400 | ToolType 不受支持。 | 检查工具类型名称是否在支持范围内。 | 改为支持的工具类型。 |
InvalidParameterValue.Timeout | 400 | Timeout 格式错误或超出限制。 | 检查时长格式和取值范围。 | 改为有效的超时值后重试。 |
InvalidParameterValue.SandboxTool | 400 | Tool 名称冲突或 Tool 参数值非法。 | 检查 Tool 名称是否重复，以及 Tool 相关参数是否有效。 | 调整 Tool 名称或修正参数。 |
InvalidParameterValue.ToolIds | 400 | ToolIds 格式错误，或数量超出限制。 | 检查 ID 格式和列表长度。 | 修正 ID 列表后重试。 |
InvalidParameterValue.InstanceIds | 400 | InstanceIds 格式错误，或数量超出限制。 | 检查 ID 格式和列表长度。 | 修正 ID 列表后重试。 |
InvalidParameterValue.InstanceID | 400 | 单个 InstanceID 格式错误。 | 检查实例 ID 是否符合接口格式。 | 使用正确的实例 ID。 |
InvalidParameterValue.NetworkMode | 400 | NetworkMode 取值错误。 | 检查网络模式字段是否为支持的枚举值。 | 改为支持的网络模式。 |
InvalidParameterValue.UserUin | 400 | UserUin 格式错误。 | 检查账号标识字段格式。 | 使用有效的 UserUin。 |
InvalidParameterValue.Quota | 400 | 配额参数值错误。 | 检查配额字段是否为有效整数且未超出范围。 | 修正配额值后重试。 |
InvalidParameter.TagKeyConflict | 400 | 配额组的 tag_key 与现有配置冲突。 | 检查同一账号下是否已存在其他 tag_key 的配额组。 | 调整标签键，或复用已有配额组。 |
MissingParameter.RoleArn | 400 | 使用需要角色授权的能力时缺少 RoleArn。 | 检查存储挂载或凭证相关配置。 | 补齐 RoleArn。 |
InvalidParameterValue.RoleArn | 400 | RoleArn 格式错误。 | 检查 ARN 格式。 | 使用有效的角色 ARN。 |
InvalidParameterValue.RoleName | 400 | 角色名格式错误，或角色名不在允许范围内。 | 检查角色名格式和约束。 | 改为允许的角色名。 |
InvalidParameterValue.StorageMount | 400 | StorageMount 配置格式错误。 | 检查挂载配置结构。 | 按接口要求修正挂载配置。 |
InvalidParameterValue.MountOption | 400 | MountOption 配置错误。 | 检查挂载选项是否合法。 | 修正挂载选项后重试。 |
MissingParameter.VPCParameters | 400 | 使用 VPC 模式时缺少必填网络参数。 | 检查子网和安全组等 VPC 参数。 | 补齐必填网络参数。 |
InvalidParameterValue.SubnetId | 400 | 子网 ID 格式错误。 | 检查子网 ID 格式。 | 改为有效的子网 ID。 |
InvalidParameterValue.SecurityGroupId | 400 | 安全组 ID 格式错误。 | 检查安全组 ID 格式。 | 改为有效的安全组 ID。 |
InvalidParameterValue.Image | 400 | 镜像地址格式无效。 | 检查镜像地址是否完整且符合规范。 | 使用有效的镜像地址。 |
InvalidParameterValue.ImageRegistry | 400 | 镜像仓库类型无效。 | 检查仓库类型字段。 | 改为支持的仓库类型。 |
InvalidParameterValue.Probe | 400 | 探针配置错误。 | 检查探针字段格式和阈值。 | 修正探针配置。 |
InvalidParameterValue.EncryptionOptions | 400 | 凭证加密选项错误。 | 检查加密配置字段和值。 | 修正加密选项后重试。 |
InvalidParameterValue.CLSConfig | 400 | CLSConfig 配置错误。 | 检查日志采集相关配置结构。 | 修正 CLS 配置后重试。 |
InvalidParameterValue.TargetRegion | 400 | 目标地域与快照制作器地域不匹配。 | 检查快照来源地域和目标地域。 | 改为匹配的目标地域。 |
InvalidParameterValue.SnapshotNotSupported | 400 | 当前 Tool 配置不支持快照。 | 检查 Tool 是否启用了支持快照的配置。 | 改用支持快照的 Tool，或调整 Tool 配置。 |
InvalidParameterValue.AutoPauseNotAllowed | 400 | 当前账号未开通自动暂停能力。 | 检查账号是否具备自动暂停资格。 | 关闭自动暂停配置，或联系支持确认开通条件。 |
InvalidParameterValue.AutoResumeNotAllowed | 400 | 当前账号未开通自动恢复能力。 | 检查账号是否具备自动恢复资格。 | 关闭自动恢复配置，或联系支持确认开通条件。 |
InvalidParameterValue.PauseMode | 400 | PauseMode 参数值错误。 | 检查暂停模式是否为支持值。 | 改为支持的暂停模式。 |
权限、鉴权与限流
错误码 | 错误分类 | 含义 | 诊断 | 修复方案 |
UnauthorizedOperation | 403 | 当前身份无权执行该操作。 | 检查调用身份是否具备目标资源的权限。 | 补齐所需权限后重试。 |
AuthFailure | 403 | 通用鉴权失败。 | 检查签名、身份或令牌是否有效。 | 修正鉴权信息后重试。 |
AuthFailure.UnauthorizedOperation | 403 | 鉴权通过但无权执行当前操作。 | 检查 CAM 权限和资源授权范围。 | 为调用身份授予对应权限。 |
AuthFailure.Registry | 403 | 镜像仓库认证失败。 | 检查仓库凭证或访问策略。 | 修正镜像仓库认证信息。 |
AuthFailure.TokenInvalid | 403 | Token 无效或签名校验失败。 | 检查 Token 是否被篡改、格式是否正确。 | 重新获取有效 Token。 |
AuthFailure.TokenExpired | 403 | Token 已过期。 | 检查 Token 的过期时间。 | 刷新 Token 后重试。 |
AuthFailure.CLSPushLog | 403 | 向 CLS 推送日志的权限不足。 | 检查 CLS 写入权限和角色配置。 | 为调用角色补齐 CLS 写入权限。 |
RequestLimitExceeded | 429 | 请求过于频繁，触发限流。 | 检查短时间内的调用频率。 | 使用指数退避重试：建议从 1 秒开始，逐步增加到最多 30 秒，最多重试 3 次。 |
资源不存在、不可用或被占用
错误码 | 错误分类 | 含义 | 诊断 | 修复方案 |
ResourceNotFound | 404 | 请求引用的资源不存在。 | 检查资源 ID、账号和地域。 | 使用正确的资源 ID，或先创建资源。 |
ResourceNotFound.SandboxTool | 404 | 指定的 Tool 不存在。 | 检查 ToolId 是否正确。 | 使用有效的 Tool，或先创建 Tool。 |
ResourceNotFound.SandboxInstance | 404 | 指定的 Instance 不存在。 | 检查 InstanceId 是否正确。 | 使用有效的实例 ID，或先启动实例。 |
ResourceNotFound.Instance | 404 | Credential 关联的实例不存在。 | 检查实例是否已删除或映射是否失效。 | 使用仍然存在的实例重新发起请求。 |
ResourceNotFound.QuotaGroup | 404 | 引用的配额组不存在。 | 检查标签键值对应的配额组是否已配置。 | 先创建正确的配额组，或修正标签。 |
ResourceNotFound.StorageMount | 404 | 引用的存储挂载不存在。 | 检查挂载名称是否已配置。 | 使用存在的挂载名称，或先创建挂载配置。 |
ResourceNotFound.Subnet | 404 | 子网不存在，或当前账号无权访问。 | 检查子网 ID、账号和地域。 | 改为可访问的子网。 |
ResourceNotFound.SecurityGroup | 404 | 安全组不存在，或当前账号无权访问。 | 检查安全组 ID、账号和地域。 | 改为可访问的安全组。 |
ResourceNotFound.Image | 404 | 指定镜像不存在。 | 检查镜像地址和仓库路径。 | 改为存在的镜像。 |
ResourceNotFound.Role | 404 | 指定的 CAM 角色不存在。 | 检查角色名或角色 ARN。 | 使用有效的角色配置。 |
ResourceNotFound.CLSTopic | 404 | 指定的 CLS Topic 不存在。 | 检查日志 Topic ID 和地域。 | 改为存在的 CLS Topic。 |
ResourceNotFound.SystemImage | 404 | 指定镜像不在系统镜像白名单内。 | 检查镜像是否已登记到允许列表。 | 改用已登记镜像，或联系支持确认可用镜像。 |
ResourceUnavailable | 409 | 资源当前不可用。 | 检查资源当前状态。 | 等待资源恢复后重试。 |
ResourceUnavailable.SandboxTool | 409 | Tool 当前不可用。 | 检查 Tool 是否处于可用状态。 | 等待 Tool 可用，或切换到其他 Tool。 |
ResourceUnavailable.Provider | 503 | 底层资源调度暂时不可用。 | 这类错误通常伴随脱敏后的 Message。 | 按指数退避重试；若连续 3 次仍失败，请携带 RequestId 联系支持。 |
ResourceInUse | 409 | 资源正在被使用，当前操作无法执行。 | 检查资源是否被其他操作占用。 | 等待占用结束后重试。 |
ResourceInUse.SandboxTool | 409 | Tool 正被实例或其他流程使用。 | 检查 Tool 是否仍有关联实例或未完成操作。 | 等待关联操作结束后重试。 |
ResourceInUse.CFSEndpoint | 409 | CFS 终端节点服务已存在。 | 检查是否重复创建同一终端节点。 | 复用现有终端节点，或调整配置。 |
ResourceInUse.QuotaGroupMaxBelowUsage | 409 | 配额组 max 低于当前使用量。 | 检查当前使用量与目标配额。 | 先降低实际使用量，再调整上限。 |
ResourceInUse.QuotaGroupExists | 409 | 相同标签键值的活跃配额组已存在。 | 检查是否重复创建相同配额组。 | 复用已有配额组，或删除冲突配置。 |
ResourceInsufficient.AllocatableQuota | 409 | 当前主账号剩余可分配额度不足。 | 检查账号剩余可分配配额。 | 释放闲置额度，或联系支持提升额度。 |
配额、状态冲突与操作限制
错误码 | 错误分类 | 含义 | 诊断 | 修复方案 |
LimitExceeded.SandboxTool | 429 | Tool 数量超出配额。 | 检查账号当前 Tool 使用量和配额上限。 | 删除不再使用的 Tool，或申请提升配额。 |
LimitExceeded.SandboxInstance | 429 | 实例数量超出配额。 | 检查运行中实例数量和配额上限。 | 停止或删除闲置实例，或申请提升配额。 |
LimitExceeded.PausedInstance | 429 | 暂停实例数量超出配额。 | 检查已暂停实例数量和配额上限。 | 删除或恢复部分暂停实例，或申请提升配额。 |
FailedOperation.RequestInProgress | 409 | 相同请求仍在处理中。 | 检查是否重复提交同一请求。 | 等待前一请求完成后重试。 |
FailedOperation.DuplicateRequest | 409 | 检测到重复请求。 | 检查是否重复发送相同请求。 | 使用新的请求上下文，或等待前一请求完成。 |
UnsupportedOperation | 400 | 当前操作不受支持。 | 检查接口或资源是否支持该能力。 | 改为受支持的操作路径。 |
UnsupportedOperation.SandboxInstance | 400 | 当前实例不支持该操作。 | 检查实例类型和当前能力边界。 | 改为受支持的实例操作。 |
UnsupportedOperation.SandboxTool | 400 | 当前 Tool 不支持该操作。 | 检查 Tool 类型和功能边界。 | 改为受支持的 Tool 操作。 |
OperationDenied.InvalidInstanceStatePause | 409 | 当前实例状态不允许暂停。 | 检查实例当前生命周期状态。 | 仅在允许暂停的状态下执行暂停。 |
OperationDenied.InvalidInstanceStateResume | 409 | 当前实例状态不允许恢复。 | 检查实例当前生命周期状态。 | 仅在允许恢复的状态下执行恢复。 |
OperationDenied.ConcurrentQuotaGroupOperation | 409 | 同一账号下已有其他配额组操作在执行。 | 检查是否有未完成的配额组变更。 | 等待前一操作完成后重试。 |
FailedOperation.PauseInProgress | 409 | 暂停操作正在进行中。 | 检查实例是否已经在暂停中。 | 等待本次暂停完成后重试。 |
FailedOperation.ResumeInProgress | 409 | 恢复操作正在进行中。 | 检查实例是否已经在恢复中。 | 等待本次恢复完成后重试。 |
FailedOperation.PauseFailed | 409 | 暂停操作失败。 | 检查实例状态和最近一次暂停请求。 | 根据实例状态修正条件后重试。 |
FailedOperation.ResumeFailed | 409 | 恢复操作失败。 | 检查实例状态和最近一次恢复请求。 | 根据实例状态修正条件后重试。 |
FailedOperation.DiskPauseFailed | 409 | 磁盘暂停或 Checkpoint 失败。 | 检查实例是否支持相关能力，以及实例当前状态。 | 修正前置条件后重试。 |
FailedOperation.DiskResumeFailed | 409 | 磁盘恢复或 Restore 失败。 | 检查快照或恢复上下文是否完整。 | 修正前置条件后重试。 |
存储、镜像与运行环境
错误码 | 错误分类 | 含义 | 诊断 | 修复方案 |
FailedOperation.StorageMount | 400 | 存储挂载失败，例如 bucket 或路径不存在。 | 检查 bucket、路径和挂载目标。 | 修正存储路径或目标后重试。 |
FailedOperation.PrecacheFailed | 400 | 镜像预热任务执行失败。 | 检查镜像可访问性和仓库认证。 | 修正镜像或认证配置后重试。 |
FailedOperation.ContainerStart | 400 | 容器启动失败。 | 检查镜像、启动命令和运行时依赖。 | 修正镜像或启动配置后重试。 |
FailedOperation.ContainerProbe | 400 | 探针检查失败。 | 检查探针配置与容器启动耗时。 | 调整探针参数，或修复容器启动问题。 |
FailedOperation.ImagePull | 400 | 拉取镜像失败。 | 检查镜像地址、仓库权限和网络连通性。 | 修正镜像地址或仓库认证后重试。 |
计费、日志与系统类错误
错误码 | 错误分类 | 含义 | 诊断 | 修复方案 |
FailedOperation.InsufficientBalance | 400 | 账户余额不足。 | 检查账号计费状态。 | 充值或切换到可用计费账号后重试。 |
FailedOperation | 500 | 未命中更细分子码的通用系统失败。 | 检查是否返回了通用系统消息，并记录 RequestId。 | 使用指数退避重试；若仍失败，请联系支持。 |
FailedOperation.DeleteFailed | 500 | 删除操作在平台侧失败。 | 这类错误通常是系统侧清理失败。 | 稍后重试；若持续失败，携带 RequestId 联系支持。 |
FailedOperation.CLSServiceError | 500 | CLS 服务侧处理异常。 | 这类错误通常会对外返回通用系统消息。 | 稍后重试；若持续失败，携带 RequestId 联系支持。 |
InternalError | 500 | 通用系统内部错误；对外通常会升级为更具体的公开子码。 | 记录 RequestId 并关注是否返回更具体子码。 | 稍后重试；若持续失败，联系支持。 |
InternalError.RequestProcessing | 500 | 请求处理链路内部失败。 | 通常会返回脱敏消息。 | 稍后重试；若持续失败，联系支持。 |
InternalError.SandboxProvisioning | 500 | 沙箱分配或创建阶段内部失败。 | 检查是否为瞬时平台故障。 | 稍后重试；若持续失败，联系支持。 |
InternalError.SandboxStartup | 500 | 沙箱启动阶段内部失败。 | 检查是否为瞬时平台故障。 | 稍后重试；若持续失败，联系支持。 |
InternalError.NetworkSetup | 500 | 网络建立阶段内部失败。 | 检查是否为瞬时平台故障。 | 稍后重试；若持续失败，联系支持。 |
InternalError.StorageSetup | 500 | 存储初始化阶段内部失败。 | 检查是否为瞬时平台故障。 | 稍后重试；若持续失败，联系支持。 |
InternalError.CredentialIssue | 500 | 凭证签发链路内部失败。 | 检查是否为瞬时平台故障。 | 稍后重试；若持续失败，联系支持。 |
InternalError.DependencyUnavailable | 500 | 下游依赖服务暂不可用。 | 一般为暂时性依赖故障。 | 稍后重试。 |
InternalError.VPCServiceUnavailable | 500 | VPC 服务暂不可用。 | 检查是否为短时依赖异常。 | 稍后重试；若持续失败，联系支持。 |
InternalError.NetworkSetupFailed | 500 | 网络初始化失败。 | 通常属于系统侧网络配置故障。 | 稍后重试；若持续失败，联系支持。 |
InternalError.Unknown | 500 | 未归类的系统错误。 | 这是系统错误的公开兜底子码。 | 保留 RequestId，稍后重试或联系支持。 |
常见组合场景
CLI 本地凭证问题与云端错误码混在一起
如果
agr doctor -o json --non-interactive 提示 SecretId 或 SecretKey 未配置，或者命令以退出码 4 结束并返回 Failure.Code=MISSING_CLOUD_CREDENTIALS，请先修复本地凭证。此类问题发生在请求发出之前，不会产生 Cloud API 的 Response.Error.Code。FailedOperation.RequestInProgress 与 FailedOperation.DuplicateRequest
这两个错误码都与幂等或重复提交有关，但处理方式不同：
FailedOperation.RequestInProgress 表示相同 ClientToken 的请求仍在处理。建议先等待短时间，再查询前一次请求对应的 Tool 或 Instance 状态。FailedOperation.DuplicateRequest 表示平台已识别为重复请求。此时应先检查前一次请求结果，而不是立即再次提交相同请求。ResourceUnavailable.SandboxTool 与实例启动失败同时出现
如果 Tool 尚未进入可用状态，实例启动、恢复或其他依赖 Tool 的操作可能继续失败。请先查询 Tool 状态，再决定是等待 Tool 转为可用，还是根据状态原因修复配置。
RequestLimitExceeded 与 LimitExceeded.* 容易混淆
RequestLimitExceeded 是频率限制，适合短时指数退避重试。LimitExceeded.SandboxTool、LimitExceeded.SandboxInstance、LimitExceeded.PausedInstance 和 ResourceInsufficient.AllocatableQuota 是容量或配额问题。此类错误需要释放资源、调整配额组或申请提升额度，而不是只做重试。ResourceUnavailable.Provider、FailedOperation 与 InternalError.*
这三类错误通常表示平台或依赖侧的瞬时问题。对外
Message 可能统一表现为 Internal server error。如果短时重试仍失败，请保留 RequestId、资源 ID 和触发命令，再联系支持。重试建议
400、403、404 类错误通常不能通过直接重试恢复，应先修正请求参数、权限、镜像仓库认证或资源引用。409 类错误需要先区分具体原因。FailedOperation.RequestInProgress、FailedOperation.PauseInProgress、FailedOperation.ResumeInProgress 和部分 ResourceUnavailable.* 适合等待状态变化后重试；FailedOperation.DuplicateRequest、ResourceInUse.*、ResourceInUse.QuotaGroupExists 更适合先查询已有结果或清理冲突资源。429、500、503 类错误适合指数退避重试。建议从 1 秒开始，按 2、4、8 秒递增，单次等待上限 30 秒，最多重试 3 次。连续失败后请联系支持。对配额相关错误，建议先执行只读查询确认 Tool、Instance 和配额占用情况，再决定是否停止闲置实例、删除不再使用的 Tool，或申请提升配额。
遇到问题？
Response.Error.CodeResponse.Error.MessageRequestId触发错误的
Action 或 CLI 命令相关资源 ID，例如
ToolId、InstanceId请求发生时间、地域，以及是否已经重试
