alibabacloud-error-troubleshoot

Alibaba Cloud OpenAPI 故障排查

通过 Aliyun CLI 命令调用 OpenAPI Explorer 故障排查 API，帮助用户诊断 Alibaba Cloud OpenAPI 调用失败的问题。这些 CLI 命令调用的后端与 OpenAPI Diagnostic Portal 相同。

---

前置条件

安装 Aliyun CLI

运行 aliyun version，确认版本为 >= 3.4.0。如果尚未安装或版本过旧，请参阅 references/cli-installation-guide.md。

安装 OpenAPI Explorer 插件（必须先执行）

此技能依赖 aliyun-cli-openapiexplorer 插件，该插件提供所需的三个 CLI 命令： openapiexplorer get-own-request-log、openapiexplorer get-request-log、openapiexplorer get-error-code-solutions。

插件名称是 aliyun-cli-openapiexplorer（不是 openapiexplorer）。 安装命令使用 --names：

aliyun configure set --auto-plugin-install true
aliyun plugin install --names aliyun-cli-openapiexplorer
aliyun plugin update

在运行任何故障排查命令之前，请确认插件可用：

aliyun plugin list | grep openapiexplorer
aliyun openapiexplorer get-own-request-log --help

命令格式规则（强制）。 此技能中的所有故障排查命令都必须使用 openapiexplorer 插件下的精确连字符格式：

• aliyun openapiexplorer get-own-request-log ...
• aliyun openapiexplorer get-request-log ...
• aliyun openapiexplorer get-error-code-solutions ...

严格禁止使用 PascalCase 子命令。 切勿尝试编造任何 aliyun <product> <PascalCaseApi> 格式的调用来替代。如果故障排查命令返回 not a valid api，说明缺少 openapiexplorer 插件——请重新运行上述安装命令，不要改用 ActionTrail、网页搜索，也不要重新发起原先失败的 API 调用。这三个命令仅存在于 openapiexplorer 插件下，在核心产品子命令中没有对应命令。

检查 Alibaba Cloud 凭证

运行 aliyun configure list，确认已配置凭证。 如果未显示有效配置文件，停止并请用户在当前会话之外运行 aliyun configure。

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户将 AK/SK 粘贴到对话中
• 仅使用 aliyun configure list 检查凭证状态
• 展示结果时，隐藏日志输出中的敏感字段（authenticationInfo.ak、令牌等）

---

可观测性（每条 aliyun 命令都必须遵守）

加载此技能时，为整个会话生成一个随机会话 ID：

• **格式：**32 位小写十六进制字符串（例如 a1b2c3d4e5f6789012345678901234ab）
• **时间：**在会话开始时生成一次；本会话中的每次云 API 调用都重复使用同一值
• **占位符：**在以下所有命令中将其用作 {session-id}

规则：每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。

本地实用程序命令（例如 configure、plugin、version）不支持此标志，应排除在外。

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

---

场景说明

当用户需要以下操作时，请使用此技能：

• 按 Request ID（API 响应或错误中的 UUID）查找请求日志详情
• 了解 API 调用失败的原因（HTTP 状态、错误代码、调用方身份、请求参数）
• 获取特定错误代码的官方诊断解决方案
• 排查 OpenAPI 调用中的权限 / RAM / 限流 / 参数问题

---

RAM 权限要求

API	CLI 命令	用途
GetOwnRequestLog	get-own-request-log	查询当前账号发出的 API 调用日志
GetRequestLog	get-request-log	查询同一主账号下 Request ID 的日志，包括主账号及其所有子账号
GetErrorCodeSolutions	get-error-code-solutions	获取错误代码的诊断解决方案

最低限度的 RAM 策略 JSON，请参阅 references/ram-policies.md。

权限失败处理： 如果调用返回 Unauthorized 或 AccessDenied，请停止操作并提供 references/ram-policies.md。未经用户明确确认，不要尝试改用其他账号重试。

---

核心诊断工作流

请遵循此决策树。完整详情请参阅：references/troubleshooting-workflow.md。

User has Request ID?
├── YES → Step 1: Query request log
│         ├── Default: get-own-request-log (current account only)
│         └── Request ID from sibling sub-account or main account: get-request-log
│         ├── Step 1 returns NotFound.RequestLog (404)?
│         │     └── TERMINATE: do NOT call get-error-code-solutions with `NotFound.RequestLog`.
│         │        Report log-unavailable cause (expired / wrong scope / no permission),
│         │        ask user for a fresh Request ID or the original error code, end the run.
│         ├── Step 2: Extract errorCode, errorMessage, product from logInfo.basicInfo
│         └── Step 3: If errorCode present → get-error-code-solutions
│            → Step 4: Summarize root cause + solutions + next steps
└── NO, only error code/message
    └── Step 3 directly: get-error-code-solutions (provide product if known)

⛔ 日志 NotFound 时必须停止： NotFound.RequestLog 是 troubleshoot-API 对“无可用日志”的状态标记，不是用户失败调用的业务错误代码。将其传给 get-error-code-solutions 会返回不相关或空的结果，严格禁止这样做。工作流必须始终在 NotFound 分支结束，并改为向用户显示恢复提示。

步骤 1：按 Request ID 查询请求日志

Request ID 格式： UUID，大写（例如 BE7C768F-946F-5B46-80D4-F22FCFAF67C0）。

选择合适的命令：

命令	范围	使用时机
get-own-request-log	仅当前账号自己的 API 调用	默认——用户排查自己失败的 API 调用
get-request-log	仅限同一主账号——主账号及其下的所有子账号	子账号查询主账号或同级子账号的 Request ID；无法访问无关账号

请优先使用 get-own-request-log——这与 OpenAPI Diagnostic Portal 的行为一致（先尝试 GetOwnRequestLog，再尝试 GetRequestLog）。

# Default: current account
aliyun openapiexplorer get-own-request-log \
  --log-request-id <REQUEST_ID> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

# Same parent account — main account or sibling sub-accounts
aliyun openapiexplorer get-request-log \
  --log-request-id <REQUEST_ID> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

从 logInfo 提取关键字段（使用 --cli-query 投影）：

aliyun openapiexplorer get-own-request-log \
  --log-request-id <REQUEST_ID> \
  --cli-query 'logInfo.basicInfo.{product:product,api:api,errorCode:errorCode,errorMessage:errorMessage,httpStatusCode:httpStatusCode,regionId:regionId,logRequestId:logRequestId}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

字段路径	含义
logInfo.basicInfo.product	产品代码（查询解决方案时需要）
logInfo.basicInfo.api	API 操作名称
logInfo.basicInfo.errorCode	失败调用的错误代码
logInfo.basicInfo.errorMessage	错误消息
logInfo.basicInfo.httpStatusCode	HTTP 状态（200 表示有业务错误；或为 4xx/5xx）
logInfo.basicInfo.regionId	区域
logInfo.callerInfo	调用方账号、IP、调用方类型（主账号/子账号/STS）
logInfo.parameters	发送给 API 的请求参数
logInfo.responses.responseBody	原始响应正文（可能包含嵌套错误详情）

步骤 2：分析日志

获取解决方案前，请先解读日志：

0. NotFound.RequestLog（查询本身返回 HTTP 404）——日志不可用。在此停止。 不要继续执行步骤 3。请参阅上文“日志 NotFound 时必须停止”以及下文“CLI 错误排查 → 6”。
1. HTTP 200 + errorCode 为空——调用成功；用户可能查看了错误的 Request ID，或问题出现在下游
2. HTTP 4xx/5xx 或 errorCode 非空——继续执行步骤 3
3. 限流——检查 basicInfo.throttlingResult（例如 FC.PASS 与限流代码）
4. RAM / 权限错误——在 errorCode 或响应正文中查找 AccessDenied、NoPermission、Forbidden.RAM；检查 callerInfo.callerType 以及是否涉及 STS 角色
5. 参数错误——对照 basicInfo.apiDoc 中链接的 API 文档检查 logInfo.parameters

步骤 3：获取错误码解决方案

映射到 troubleshoot-server sdkAgentService.getErrorCodeSolutions → OpenAPI GetErrorCodeSolutions。

⛔ 前置条件 — errorCode 必须来自成功获取的日志中的 logInfo.basicInfo.errorCode（或来自用户最初提交的错误报告）。绝不能将查询自身的元状态码（由 get-*-request-log 调用本身产生的 NotFound.RequestLog、Unauthorized、AccessDenied）作为 --error-code 传入。如果步骤 1 返回了 NotFound，工作流已经终止——不要进入步骤 3。

aliyun openapiexplorer get-error-code-solutions \
  --error-code <ERROR_CODE> \
  --product <PRODUCT_CODE> \
  --error-message "<ERROR_MESSAGE>" \
  --accept-language zh-CN \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-error-troubleshoot/{session-id}

参数	必需	说明
--error-code	是	来自日志的 basicInfo.errorCode 或用户的错误报告
--product	建议	来自日志的 basicInfo.product；可缩小解决方案匹配范围
--error-message	可选	同一错误码存在多个解决方案时，可提高匹配质量
--accept-language	可选	zh-CN（默认）或 en-US；无英文内容时为空

产品代码来源：

• 步骤 1 中的 logInfo.basicInfo.product（首选）
• OpenAPI 门户 URL：https://api.aliyun.com/product/<ProductCode> → ProductCode 是 /product/ 后面的字段

清晰呈现每个解决方案的 title/content。空的 solutions 数组表示没有整理好的解决方案——改用日志分析和 API 文档。

步骤 4：呈现诊断结果

始终包含：

1. 发生了什么 — API、产品、地域、HTTP 状态、错误码/消息
2. 调用方是谁 — 调用方账号类型和 ID（对 AK 脱敏）
3. 根本原因 — 来自日志分析和解决方案
4. 建议操作 — 来自解决方案内容，以及发现的任何参数/RAM 修复建议
5. 使用的 CLI 命令 — 完整且可直接复制粘贴的命令（对机密信息脱敏）

---

命令速查

完整参数列表和示例请参阅 references/api-reference.md。

CLI	API	说明
aliyun openapiexplorer get-own-request-log	GetOwnRequestLog	当前账号的请求日志
aliyun openapiexplorer get-request-log	GetRequestLog	同一主账号下的请求日志
aliyun openapiexplorer get-error-code-solutions	GetErrorCodeSolutions	错误码诊断解决方案

---

全局规则

• 始终优先使用 get-own-request-log，除非 Request ID 属于主账号或同一主账号下的另一个子账号
• Request ID 必须是大写 UUID — 调用前先规范化
• 只要日志中提供了 --product，调用 get-error-code-solutions 时就始终传入
• 不要猜测产品代码——应从日志或 OpenAPI 门户 URL 推导
• 日志会过期 — 如果返回 NotFound.RequestLog，日志可能已过期（通常保留约 3 天），或者调用方缺少权限
• 在有帮助时链接到 OpenAPI 故障排查门户：https://api.aliyun.com/troubleshoot?q=<ErrorCode>&product=<Product>

---

CLI 错误故障排查

用户报告错误时，请按顺序逐项检查：

1. CLI 版本 — aliyun version 是否 >= 3.4.0？
2. 已安装插件 — aliyun plugin list | grep openapiexplorer？
3. 凭据 — aliyun configure list 是否显示有效的配置文件？
4. 请求 ID 格式 — 是否为大写 UUID？
5. 命令与范围不匹配 — 主账号或同级子账号的请求 ID 调用 get-own-request-log 时返回 404？请改用 get-request-log 重试（仅限同一父账号）。如果仍返回 404，则该请求 ID 来自无关账号、已过期或无效。
6. NotFound.RequestLog (404) — 日志已过期、请求 ID 错误或没有权限。消息：“与此 logRequestId 相关的日志不存在、已过期，或您没有查看权限。”
   • 硬性规则： 必须在此处终止诊断工作流。不要调用 get-error-code-solutions 并传入 --error-code NotFound.RequestLog（也不要传入 get-*-request-log 调用产生的 Unauthorized / AccessDenied 等查询接口自身的元状态码）。这些是故障排查 API 本身的状态码，并非用户失败调用的状态码——查询解决方案会返回无关或空结果。
   • 向用户发送的标准恢复消息： 说明日志不可用（约 3 天后过期 / 请求 ID 超出当前账号范围 / 缺少 GetRequestLog 权限），然后请用户提供以下任一信息：（a）当前账号最近一次失败调用生成的新请求 ID；或（b）用户应用程序日志中的原始错误码。然后结束本轮对话。
7. Unauthorized / AccessDenied — 请参阅 references/ram-policies.md
8. 解决方案为空 — 没有整理好的解决方案；请改为分析日志字段和 API 文档

完整操作手册：references/troubleshooting-workflow.md。

---

参考文档

文档	描述
references/cli-installation-guide.md	CLI >= 3.4.0 的安装、插件设置和凭据
references/api-reference.md	三个 API 的完整 CLI 命令参考
references/troubleshooting-workflow.md	端到端故障排查操作手册及示例
references/ram-policies.md	故障排查 API 所需的最低 RAM 策略