iflytek/astron-agent · error · CustomException

CodeConvert.sparkLinkCode(code)

CodeConvert.sparkLinkCode(code)

Error message

{message}

What it means

After calling the Spark Link tool, run() checks the response header code; a non-zero code is converted via CodeConvert.sparkLinkCode and raised as a CustomException carrying the server-supplied message. This is an application-level error returned by the Link API itself — the HTTP call succeeded but the tool execution failed on the server side.

Solutions

  1. Read the message and cause_error in the exception to see the Link server's error description
  2. Validate the tool input parameters against the tool schema before calling run()
  3. Check Link API credentials/authorization and the tool's status on the Link platform; fix the reported cause and retry
Defensive patterns

Strategy: try-catch

Validate before calling

# validate tool inputs against the fetched tool schema before run()
jsonschema.validate(tool_input, tool_schema)

Try / catch

try:
    result = link_client.run(...)
except CustomException as e:
    log.error("Link API error", extra={"cause": e.cause_error})
    # inspect e.cause_error for server-side code/message

Prevention

When it happens

Trigger: run() executes a Link tool and the response body link_response["header"]["code"] is any value other than 0.

Common situations: Invalid or expired Link credentials, tool disabled on the Link platform, malformed tool input rejected by the service, or Link-side rate limiting/quota exhaustion.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/899eb93cc5b2fdb9. Report an issue: GitHub.

Appendix: source

Thrown at core/workflow/engine/nodes/plugin_tool/link_client.py:311

                    CodeEnum.SPARK_LINK_CONNECTION_ERROR,
                    err_msg="Tool request failed, connection error",
                    cause_error="Tool request failed, connection error",
                ) from e
            except Exception as e:
                # Handle other exceptions
                raise e

            await link_tool_span.add_info_events_async(
                {"link_response": json.dumps(link_response, ensure_ascii=False)}
            )

            # Process response and handle errors
            code = link_response["header"]["code"]
            message = link_response["header"]["message"]

            if code != 0:
                # Handle tool execution errors
                raise CustomException(
                    err_code=CodeConvert.sparkLinkCode(code),
                    err_msg=message,
                    cause_error=json.dumps(link_response, ensure_ascii=False),
                )
            else:
                # Extract and parse successful response
                tool_response_text = link_response["payload"]["text"]["text"]
                return json.loads(tool_response_text)


class Link:
    """
    Link system client for managing and executing plugin tools.

    This class handles communication with the Link system to retrieve tool schemas
    and manage tool execution. It parses OpenAPI schemas and creates Tool instances
    for each available operation.
    """

View on GitHub (pinned to 5e758547a8)