Issue/Introduction

This article applies to access failures, authentication failures, unexpected response codes, polling timeouts, insufficient permissions, and parameter errors when you call ZStack Cloud APIs through curl, Postman, a Java or Python SDK, or a third-party system. These issues are usually related to the request address, port, HTTP method, password encryption, asynchronous API polling, proxy mapping, or account permissions.

Symptoms

• A Java SDK call returns 405 and reports an incorrect request method.
• An asynchronous API returns a polling address, but subsequent calls to that address return Request timed out.
• A subaccount call to a quota, IPsec, or enterprise-management API reports a permission or session issue.
• An API returns status code 202, 503, or 404, and the caller incorrectly treats the response as an API failure.
• When an API is accessed through a proxy address, the polling address still contains the management node's internal address.
• A Python SDK call to the API for creating a volume from a snapshot times out while querying the task.

Environment

• Product: ZCF
• Component: Cloud
• Objects: ZStack Cloud; OpenAPI, Java SDK, Python SDK, sessions, AK/SK, IAM, billing, quotas, and ZWatch
• Versions: 4.x-4.8.38

Possible causes

• The request URL, port, protocol, or management-node or VIP address is incorrect.
• The API uses the wrong HTTP method, such as GET instead of POST or PUT when creating a resource.
• The sign-in password uses the wrong encryption method, or the calling tool encrypts a SHA-512 password a second time.
• The polling address returned by an asynchronous API is not rewritten to use the proxy address, so an external caller cannot access the internal address.
• The API represents an asynchronous task, but the caller does not continue querying the result through the 202 polling mechanism.
• The subaccount lacks permission and calls an API available only to admin or a specific role.
• The SDK's default task-polling timeout is too short while a long-running task continues in the background.

Resolution

1. Verify basic API access information

• Confirm whether the request address is a management-node address, VIP address, or proxy-mapped address.
• Confirm that the port, protocol, firewall, WAF, NAT, load balancer, and address mapping permit traffic.
• Reproduce the smallest possible call with curl or Postman to exclude the SDK abstraction layer.

curl -k -i http://<mn-or-vip>:8080/zstack/v1/

2. Verify sign-in and authentication

• In session mode, sign in first and include the session UUID in subsequent requests.
• Use SHA-512 for the account sign-in password as required by the API. If the calling tool encrypts it automatically, avoid passing an already encrypted password for encryption again.
• In AK/SK mode, check the date, signature, Authorization field, and time on the caller machine.
• RequestTimeTooSkewed usually indicates that the time difference between the caller and the platform is excessive. If the time difference is greater than 15 seconds, synchronize the time on both sides and retry.

3. Verify the HTTP method and parameters

• Confirm in the developer manual that the GET, POST, PUT, or DELETE method matches the API.
• For action APIs, confirm the body structure, field location, and systemTags and userTags formats.
• For query APIs, confirm the fields, conditions, ZQL conditions, and enum values.

4. Understand asynchronous API polling

• Except for a small number of APIs such as sign-in, non-GET APIs are usually asynchronous.
• When the first successful call returns 202, continue sending GET requests to the polling address in the response body.
• Common polling responses are:
• 202: The task is still running.
• 200: The task succeeded.
• 503: The task failed, and error information is returned.
• 404: The polling address expired or is incorrect.
• If an external proxy mapping is used, replace the internal address in the polling address with the proxy address before accessing it.

5. Check permissions and account type

• Reproduce the same API with the admin account to determine whether the subaccount permission boundary causes the issue.
• Quota, some enterprise-management, IPsec, and role APIs might require specific permissions or UI feature authorization.
• If the account also cannot see the corresponding feature in the UI, the API failure is usually caused by missing permissions rather than the session itself.

6. Check management logs

grep -a -n "<api-id-or-session-uuid>" /usr/local/zstack/apache-tomcat/logs/management-server.log*
grep -a -n "API\|apiId\|errorCode" /usr/local/zstack/apache-tomcat/logs/management-server.log*

• Use the API ID, session UUID, resource UUID, or error code to trace the actual issue in the management logs.
• For high-concurrency operations such as bulk creation, bulk deletion, or snapshot creation, also check underlying resource locks, storage I/O, and the task queue.

Notes

• Base the troubleshooting conclusion on the current version, service status, logs, cluster health, recent changes, and on-site impact scope.
• Before high-risk operations such as database modification, forced deletion, OSD or MON reconstruction, pool deletion, service restart, or network changes, complete backups, obtain approval, and confirm the plan with technical support.