iflytek/astron-agent · error · BusinessException

RESPONSE_FAILED

RESPONSE_FAILED

Error message

${message}

What it means

ToolServiceCallHandler.dealResult inspects respData.getCode() from the tool-service response. Any non-zero code becomes a BusinessException whose message is the tool service's own message — unless the code is unknown to ToolErrorStatus, in which case a generic 'tool is temporarily unavailable' message is substituted. This propagates a downstream tool-service failure to the caller.

Solutions

1. Capture the concrete message in the exception — for unmapped codes it is replaced by the generic message, so check tool-service logs or log the raw code alongside.
2. Validate the ToolProtocolDto payload (urls, protocol, parameters) before calling the tool service.
3. Verify the tool id/name exists in the tool service if the message indicates not-found.
4. Add the new downstream code to ToolErrorStatus so future occurrences surface the real message instead of the generic one.
5. If the code indicates a transient outage, retry with backoff.

Example fix

// before: real code/message lost for unknown codes
throw new BusinessException(ResponseEnum.RESPONSE_FAILED, message);

// after: keep the code for diagnosability
throw new BusinessException(ResponseEnum.RESPONSE_FAILED,
    message + " (tool service code: " + respData.getCode() + ")");

// Validate payload before calling the tool service
Objects.requireNonNull(req, "ToolProtocolDto required");
Assert.hasText(req.getName(), "tool name required");
Assert.hasText(req.getProtocol(), "protocol required");

try {
    toolServiceCallHandler.someOperation(req);
} catch (BusinessException e) {
    if ("The tool is temporarily unavailable, please try again later".equals(e.getMessage())) {
        // unmapped downstream code: retry with backoff or degrade gracefully
    } else {
        throw e; // real business rejection from tool service
    }
}

When it happens

Trigger: Any tool create/update/call operation (e.g. toolCreate via TOOL_VERSIONS_URL) where the tool service replies with code != 0 — tool not found, invalid protocol DTO, auth failure, or tool-service internal error.

Common situations: Tool service outage or version upgrade returning new/unmapped error codes (mapped to the generic unavailable message); passing a tool id or payload the tool service rejects; mismatched API versions between toolkit and tool service.

Related errors

• PARAMETER_ERROR
• OPEN_AI_API_ERROR
• REPO_KNOWLEDGE_ADD_FAILED
• REPO_KNOWLEDGE_MODIFY_FAILED
• REPO_FILE_DELETE_FAILED

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

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/handler/ToolServiceCallHandler.java:49

    public ToolProtocolDto toolDebug(ToolDebugRequest req) {
        String url = apiUrl.getToolUrl() + TOOL_MANAGE_URL + "/tool_debug";
        log.info("toolDebug request url:{}\ndata:{}", url, JSON.toJSONString(req));
        String resp = OkHttpUtil.post(url, JSON.toJSONString(req));
        log.info("toolDebug response data:{}", resp);
        return JSON.parseObject(resp, ToolProtocolDto.class);
    }

    public void dealResult(ToolResp respData) {
        if (respData == null) {
            throw new BusinessException(ResponseEnum.COMMON_REMOTE_CALLER_FAILED);
        }
        if (respData.getCode() != 0) {
            String message = respData.getMessage();
            if (ToolErrorStatus.find(respData.getCode()) == null) {
                message = "The tool is temporarily unavailable, please try again later";
            }
            throw new BusinessException(ResponseEnum.RESPONSE_FAILED, message);
        }
    }


    public ToolResp toolCreate(ToolProtocolDto req) {
        String url = apiUrl.getToolUrl() + TOOL_VERSIONS_URL;
        log.info("toolCreate request url:{}\ndata:{}", url, JSON.toJSONString(req));
        String resp = OkHttpUtil.post(url, JSON.toJSONString(req));
        log.info("toolCreate response data:{}", resp);
        return JSON.parseObject(resp, ToolResp.class);
    }

    public ToolResp toolUpdate(ToolProtocolDto req) {
        String url = apiUrl.getToolUrl() + TOOL_VERSIONS_URL;
        log.info("toolAddVersion request url:{}\ndata:{}", url, JSON.toJSONString(req));
        String resp = OkHttpUtil.put(url, JSON.toJSONString(req));
        log.info("toolUpdate response data:{}", resp);
        return JSON.parseObject(resp, ToolResp.class);

View on GitHub (pinned to 5e758547a8)