Alibaba Cloud OpenAPI Troubleshoot

Guide users to diagnose Alibaba Cloud OpenAPI call failures using the OpenAPI Explorer troubleshoot APIs exposed as Aliyun CLI commands. These CLI commands call the same backend as the OpenAPI Diagnostic Portal.

Prerequisites

Install Aliyun CLI

Run aliyun version to verify version >= 3.4.0. If not installed or outdated, follow references/cli-installation-guide.md.

Install OpenAPI Explorer Plugin (MUST do this first)

This skill depends on the aliyun-cli-openapiexplorer plugin, which provides the three required CLI commands: openapiexplorer get-own-request-log, openapiexplorer get-request-log, openapiexplorer get-error-code-solutions.

Plugin name is aliyun-cli-openapiexplorer (NOT openapiexplorer). The install command uses --names:

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

Verify it is available before running any troubleshoot command:

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

Command format rule (mandatory). Every troubleshoot command in this skill MUST use the exact kebab-case form under the openapiexplorer plugin:

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

PascalCase subcommands are strictly forbidden. Never invent or attempt any aliyun <product> <PascalCaseApi> style call as a substitute. If a troubleshoot command returns not a valid api, the openapiexplorer plugin is missing — re-run the install command above instead of switching to ActionTrail, web search, or re-issuing the original failing API. These three commands live only under the openapiexplorer plugin and have no equivalent in core product subcommands.

Check Alibaba Cloud Credentials

Run aliyun configure list to verify credentials are configured. If no valid profile is shown, STOP and ask the user to run aliyun configure outside this session.

Security rules:

NEVER read, echo, or print AK/SK values
NEVER ask the user to paste AK/SK into the conversation
ONLY use aliyun configure list to check credential status
Redact sensitive fields in log output (authenticationInfo.ak, tokens, etc.) when presenting results

Observability (MUST follow for every aliyun command)

Upon loading this skill, generate a random session ID once for the entire session:

Format: 32-character lowercase hex string (e.g. a1b2c3d4e5f6789012345678901234ab)
When: Generate once at session start; reuse the same value for every cloud API call in this session
Placeholder: Use it as {session-id} in all commands below

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag.

Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

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

Scenario Description

Use this skill when the user wants to:

Look up request log details by Request ID (UUID from an API response or error)
Understand why an API call failed (HTTP status, error code, caller identity, request parameters)
Get official diagnostic solutions for a specific error code
Troubleshoot permission / RAM / throttling / parameter issues on OpenAPI calls

RAM Permission Requirements

| API | CLI Command | Purpose | |-----|-------------|---------| | GetOwnRequestLog | get-own-request-log | Query logs for API calls made by the current account | | GetRequestLog | get-request-log | Query logs for Request IDs under the same parent account — main account and all its sub-accounts | | GetErrorCodeSolutions | get-error-code-solutions | Fetch diagnostic solutions for an error code |

See references/ram-policies.md for minimum RAM policy JSON.

Permission failure handling: If a call returns Unauthorized or AccessDenied, stop and surface references/ram-policies.md. Do not retry with a different account without explicit user confirmation.

Core Diagnostic Workflow

Follow this decision tree. Full details: 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)

⛔ Hard stop on log-NotFound: NotFound.RequestLog is the troubleshoot-API's own status for "no log available", not a business error code of the user's failed call. Feeding it to get-error-code-solutions will return irrelevant or empty results and is strictly forbidden. Always end the workflow at the NotFound branch and surface a user-facing recovery message instead.

Step 1: Query Request Log by Request ID

Request ID format: UUID, uppercase (e.g. BE7C768F-946F-5B46-80D4-F22FCFAF67C0).

Choose the right command:

| Command | Scope | When to use | |---------|-------|-------------| | get-own-request-log | Current account's own API calls only | Default — user troubleshooting their own failed API call | | get-request-log | Same parent account only — main account + all sub-accounts under it | Sub-account querying main account or sibling sub-account Request IDs; cannot access unrelated accounts |

Prefer get-own-request-log first — this mirrors the OpenAPI Diagnostic Portal behavior (GetOwnRequestLog is tried before 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}

Extract key fields from logInfo (use --cli-query to project):

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}

| Field path | Meaning | |------------|---------| | logInfo.basicInfo.product | Product code (needed for solution lookup) | | logInfo.basicInfo.api | API action name | | logInfo.basicInfo.errorCode | Error code from the failed call | | logInfo.basicInfo.errorMessage | Error message | | logInfo.basicInfo.httpStatusCode | HTTP status (200 with business error vs 4xx/5xx) | | logInfo.basicInfo.regionId | Region | | logInfo.callerInfo | Caller account, IP, caller type (main/sub/STS) | | logInfo.parameters | Request parameters sent to the API | | logInfo.responses.responseBody | Raw response body (may contain nested error details) |

Step 2: Analyze the Log

Before fetching solutions, interpret the log:

NotFound.RequestLog (HTTP 404 from the lookup itself) — log is unavailable. STOP HERE. Do NOT proceed to Step 3. See "Hard stop on log-NotFound" above and "Troubleshooting CLI Errors → 6" below.
HTTP 200 + empty errorCode — call succeeded; user may be looking at the wrong Request ID or a downstream issue
HTTP 4xx/5xx or non-empty errorCode — proceed to Step 3
Throttling — check basicInfo.throttlingResult (e.g. FC.PASS vs throttle codes)
RAM / permission errors — look for AccessDenied, NoPermission, Forbidden.RAM in errorCode or response body; check callerInfo.callerType and whether STS role is involved
Parameter errors — cross-check logInfo.parameters against API documentation linked in basicInfo.apiDoc

Step 3: Get Error Code Solutions

Maps to troubleshoot-server sdkAgentService.getErrorCodeSolutions → OpenAPI GetErrorCodeSolutions.

⛔ Precondition — errorCode MUST come from logInfo.basicInfo.errorCode of a successfully retrieved log (or from the user's original error report). Never pass the lookup's own meta-status codes (NotFound.RequestLog, Unauthorized, AccessDenied produced by the get-*-request-log call itself) as --error-code. If Step 1 returned NotFound, the workflow has already terminated — do not enter Step 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}

| Parameter | Required | Notes | |-----------|----------|-------| | --error-code | Yes | From log basicInfo.errorCode or user's error report | | --product | Recommended | From log basicInfo.product; narrows solution matches | | --error-message | Optional | Improves match quality when multiple solutions exist for the same code | | --accept-language | Optional | zh-CN (default) or en-US; empty if no English content |

Product code sources:

logInfo.basicInfo.product from Step 1 (preferred)
OpenAPI portal URL: https://api.aliyun.com/product/<ProductCode> → ProductCode is the segment after /product/

Present each solution's title/content clearly. An empty solutions array means no curated solution exists — fall back to log analysis and API documentation.

Step 4: Present Diagnosis

Always include:

What happened — API, product, region, HTTP status, error code/message
Who called — caller account type and ID (redact AK)
Root cause — from log analysis + solutions
Recommended actions — from solution content + any parameter/RAM fixes identified
CLI commands used — full copy-paste-ready commands (redact secrets)

Command Quick Reference

See references/api-reference.md for full parameter lists and examples.

| CLI | API | Description | |-----|-----|-------------| | aliyun openapiexplorer get-own-request-log | GetOwnRequestLog | Current account's request log | | aliyun openapiexplorer get-request-log | GetRequestLog | Request log under the same parent account | | aliyun openapiexplorer get-error-code-solutions | GetErrorCodeSolutions | Error code diagnostic solutions |

Global Rules

Always prefer get-own-request-log unless the Request ID belongs to the main account or another sub-account under the same parent account
Request ID must be uppercase UUID — normalize before calling
Always pass --product to get-error-code-solutions when available from the log
Do not guess product codes — derive from log or OpenAPI portal URL
Logs expire — if NotFound.RequestLog, the log may have expired (typically retained ~3 days) or the caller lacks permission
Link to OpenAPI troubleshoot portal when helpful: https://api.aliyun.com/troubleshoot?q=<ErrorCode>&product=<Product>

Troubleshooting CLI Errors

Walk through in order when the user reports errors:

CLI version — aliyun version >= 3.4.0?
Plugin installed — aliyun plugin list | grep openapiexplorer?
Credentials — aliyun configure list shows valid profile?
Request ID format — uppercase UUID?
Wrong command for scope — 404 on get-own-request-log for main account or sibling sub-account Request ID? Retry with get-request-log (same parent account only). If still 404, the Request ID is from an unrelated account, expired, or invalid
NotFound.RequestLog (404) — log expired, wrong Request ID, or no permission. Message: "The log related to this logRequestId does not exist, has expired, or you do not have permission to view it."
- Hard rule: TERMINATE the diagnostic workflow here. Do NOT call get-error-code-solutions with --error-code NotFound.RequestLog (or any of the lookup's own meta-status codes like Unauthorized / AccessDenied produced by the get-*-request-log call). They are status codes of the troubleshoot API itself, not of the user's failing call — solution lookup will return irrelevant or empty results.
- Standard recovery message to the user: explain that the log is unavailable (expired ~3 days / Request ID is outside current account scope / lacks GetRequestLog permission), then ask for either (a) a fresh Request ID generated by a recent failing call from the current account, or (b) the original error code from the user's application logs — and end this turn.
Unauthorized / AccessDenied — see references/ram-policies.md
Empty solutions — no curated solution; analyze log fields and API docs instead

Full playbook: references/troubleshooting-workflow.md.

Reference Documents

| Document | Description | |----------|-------------| | references/cli-installation-guide.md | CLI >= 3.4.0 install, plugin setup, credentials | | references/api-reference.md | Full CLI command reference for all three APIs | | references/troubleshooting-workflow.md | End-to-end diagnostic playbook with examples | | references/ram-policies.md | Minimum RAM policies for troubleshoot APIs |