{"record":{"id":"de280ee43da2f807","repo":"iflytek/astron-agent","slug":"response-failed-de280e","errorCode":"RESPONSE_FAILED","errorMessage":"${message}","messagePattern":"\\$\\{message\\}","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/handler/ToolServiceCallHandler.java","lineNumber":49,"sourceCode":"\n    public ToolProtocolDto toolDebug(ToolDebugRequest req) {\n        String url = apiUrl.getToolUrl() + TOOL_MANAGE_URL + \"/tool_debug\";\n        log.info(\"toolDebug request url:{}\\ndata:{}\", url, JSON.toJSONString(req));\n        String resp = OkHttpUtil.post(url, JSON.toJSONString(req));\n        log.info(\"toolDebug response data:{}\", resp);\n        return JSON.parseObject(resp, ToolProtocolDto.class);\n    }\n\n    public void dealResult(ToolResp respData) {\n        if (respData == null) {\n            throw new BusinessException(ResponseEnum.COMMON_REMOTE_CALLER_FAILED);\n        }\n        if (respData.getCode() != 0) {\n            String message = respData.getMessage();\n            if (ToolErrorStatus.find(respData.getCode()) == null) {\n                message = \"The tool is temporarily unavailable, please try again later\";\n            }\n            throw new BusinessException(ResponseEnum.RESPONSE_FAILED, message);\n        }\n    }\n\n\n    public ToolResp toolCreate(ToolProtocolDto req) {\n        String url = apiUrl.getToolUrl() + TOOL_VERSIONS_URL;\n        log.info(\"toolCreate request url:{}\\ndata:{}\", url, JSON.toJSONString(req));\n        String resp = OkHttpUtil.post(url, JSON.toJSONString(req));\n        log.info(\"toolCreate response data:{}\", resp);\n        return JSON.parseObject(resp, ToolResp.class);\n    }\n\n    public ToolResp toolUpdate(ToolProtocolDto req) {\n        String url = apiUrl.getToolUrl() + TOOL_VERSIONS_URL;\n        log.info(\"toolAddVersion request url:{}\\ndata:{}\", url, JSON.toJSONString(req));\n        String resp = OkHttpUtil.put(url, JSON.toJSONString(req));\n        log.info(\"toolUpdate response data:{}\", resp);\n        return JSON.parseObject(resp, ToolResp.class);","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/handler/ToolServiceCallHandler.java#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Validate the ToolProtocolDto payload (urls, protocol, parameters) before calling the tool service.","Verify the tool id/name exists in the tool service if the message indicates not-found.","Add the new downstream code to ToolErrorStatus so future occurrences surface the real message instead of the generic one.","If the code indicates a transient outage, retry with backoff."],"exampleFix":"// before: real code/message lost for unknown codes\nthrow new BusinessException(ResponseEnum.RESPONSE_FAILED, message);\n\n// after: keep the code for diagnosability\nthrow new BusinessException(ResponseEnum.RESPONSE_FAILED,\n    message + \" (tool service code: \" + respData.getCode() + \")\");","handlingStrategy":"try-catch","validationCode":"// Validate payload before calling the tool service\nObjects.requireNonNull(req, \"ToolProtocolDto required\");\nAssert.hasText(req.getName(), \"tool name required\");\nAssert.hasText(req.getProtocol(), \"protocol required\");","typeGuard":null,"tryCatchPattern":"try {\n    toolServiceCallHandler.someOperation(req);\n} catch (BusinessException e) {\n    if (\"The tool is temporarily unavailable, please try again later\".equals(e.getMessage())) {\n        // unmapped downstream code: retry with backoff or degrade gracefully\n    } else {\n        throw e; // real business rejection from tool service\n    }\n}","preventionTips":["Keep ToolErrorStatus mappings in sync with the tool service's error codes.","Validate DTOs before submission; verify tool existence before update/delete/call.","Retry only for transient/unmapped codes; surface business rejections directly to users."],"tags":["api","tool-service","upstream-error","java"],"backgroundTag":"api-error-response","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}