Test the created channel instance¶

Verify the current credentials and connection configuration of the saved channel instance.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/channels/{provider}/instances/{instance_id}/test

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the channel instance details and confirm the instance to be tested.

Set the operation-specific values used in the request:

$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID header and also as workspace_id in the path.
$PROVIDER: Channel Provider ID, as provider in the path.
$INSTANCE_ID: Channel instance ID to test, as instance_id in the path.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/channels/$PROVIDER/instances/$INSTANCE_ID/test" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	Workspace ID.
`provider`	string	Yes	Channel Provider ID.
`instance_id`	string	Yes	Channel instance ID.

Successful response¶

Returns 200 on success. The test uses the current saved credentials and configuration and updates the instance’s most recent test information.

Response example

JSON
{
  "code": 0,
  "data": {
    "instance": {
      "id": "inst_01",
      "workspace_id": "ws_01",
      "provider": "wecom",
      "channel_type": "wecom_mail",
      "name": "告警通道",
      "status": "active"
    },
    "ok": true,
    "status": "passed",
    "last_test_status": "passed",
    "last_tested_at": "2026-08-18T01:00:00Z"
  }
}

JSON
{
  "code": 0,
  "data": {
    "instance": {
      "id": "inst_01",
      "provider": "wecom"
    },
    "ok": false,
    "status": "failed",
    "last_test_status": "failed",
    "last_test_error": "<错误信息>",
    "error_code": "<ERROR_CODE>",
    "error_stage": "<STAGE>",
    "provider_error_code": "<PROVIDER_CODE>",
    "provider_error_message": "<PROVIDER_MESSAGE>",
    "error_category": "<CATEGORY>",
    "suggestion": "<SUGGESTION>",
    "last_tested_at": "2026-08-18T01:00:00Z"
  }
}

Field reference

When the external connection test fails but the test request is processed normally, the interface still returns 200:

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` when the test request is successfully processed, even if the connection test itself fails.
`data.instance`	object	An insensitive projection of the instance under test.
`data.ok`	boolean	Whether the connection test passed.
`data.status`	string	This and the latest test status.
`data.last_test_status`	string	This and the latest test status.
`data.worker_id`	string	The performer and request ID returned when available.
`data.request_id`	string	The performer and request ID returned when available.
`data.last_test_error`	string	Error message when the test fails.
`data.error_code`	string	The error code, stage, and category of the service classification.
`data.error_stage`	string	The error code, stage, and category of the service classification.
`data.error_category`	string	The error code, stage, and category of the service classification.
`data.provider_error_code`	string	Error message returned by Provider; returned when available.
`data.provider_error_message`	string	Error message returned by Provider; returned when available.
`data.suggestion`	string	Actionable fix suggestion; returned when available.
`data.last_tested_at`	string	Test time, using RFC 3339 format.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "<错误信息>"
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	Provider, instance ID, saved configuration, or credentials are not available.	Check the path; update configuration or resave credentials if necessary.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permissions for the test instance, or the credential access is denied.	Check workspace and provider side permissions.
`404`	`3`（`NOT_FOUND`）	The instance does not exist or does not belong to the Provider in the path.	Check the Provider and Instance ID.
`503`	`15`（`UNAVAILABLE`）	Channel instance services or test dependencies are temporarily unavailable.	Try again later.

Follow-up operations¶

When the connection fails Update channel instance, then retest.

Last updated on Sep 15, 2026