{"record":{"id":"a0673289a21f4e04","repo":"iflytek/astron-agent","slug":"response-failed-code","errorCode":"RESPONSE_FAILED","errorMessage":"code","messagePattern":"code","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/tool/CommonTool.java","lineNumber":86,"sourceCode":"            if (jsonObject.getInteger(\"code\") != 0) {\n                log.error(\"resp code not 0, resp = {}\", resp);\n            }\n        } catch (JSONException je) {\n            log.error(\"resp parse to json err, resp = {}\", resp);\n        }\n    }\n\n    /**\n     * Check system call response and throw exception if failed\n     *\n     * @param resp The response string to validate\n     * @return The data object from response if successful\n     * @throws BusinessException if response code is not 0\n     */\n    public static Object checkSystemCallResponse(String resp) {\n        JSONObject jsonObject = JSON.parseObject(resp);\n        if (jsonObject.getInteger(\"code\") != 0) {\n            throw new BusinessException(ResponseEnum.RESPONSE_FAILED, String.valueOf(jsonObject.getInteger(\"code\")), jsonObject.getString(\"message\"));\n        }\n        return jsonObject.get(\"data\");\n    }\n\n    public static ModelConfigProtocolDto getModelConfig(String s) {\n        return JSON.parseObject(s).getObject(\"modelConfig\", ModelConfigProtocolDto.class);\n    }\n\n    public static ModelConfigProtocolDto getModelConfig(JSONObject jsonObject) {\n        return jsonObject.getObject(\"modelConfig\", ModelConfigProtocolDto.class);\n    }\n\n    public static List<String> getToolIds(List<Tool> tools) {\n        if (tools.isEmpty()) {\n            return new ArrayList<>();\n        }\n        return tools.stream().map(Tool::getToolId).collect(Collectors.toList());\n    }","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/tool/CommonTool.java#L68-L104","documentation":"CommonTool.checkSystemCallResponse(String resp) parses a downstream system-call response as a fastjson2 JSONObject and enforces the platform convention code==0 for success. When the 'code' field is any non-zero value, it throws BusinessException(RESPONSE_FAILED) carrying the numeric code as the error message and the remote 'message' field as a template argument. The resulting exception's getMessage() is literally the remote code string (e.g. '500'), which is why this error shows up with the generic message 'code'.","triggerScenarios":"Any HTTP call whose response is fed into checkSystemCallResponse and whose JSON body has code != 0 — e.g. the target system returns {\"code\":500,...}, {\"code\":401,...} for auth failure, or a business-error code from a model/agent/tool backend.","commonSituations":"Downstream service outages or 5xx mapped into a JSON envelope; invalid or expired credentials/tokens for the target system; request parameters the remote API rejects; version drift where the remote service changed its error codes; and integration debugging where the dev only sees 'code' without knowing the wrapped remote message.","solutions":["Look at the second template argument of the BusinessException (the remote 'message' field) or catch the exception and inspect its args to learn the real reason returned by the downstream system.","Call the downstream API directly (curl/Postman with the same payload) to reproduce the non-zero code and consult that system's error-code table.","Fix the request: renew credentials, correct parameters, or retry after the remote service recovers, then confirm code==0.","Improve the call site: wrap checkSystemCallResponse and log the full raw response so future failures are diagnosable."],"exampleFix":"// before\nObject data = CommonTool.checkSystemCallResponse(resp);\n// after\ntry {\n    Object data = CommonTool.checkSystemCallResponse(resp);\n} catch (BusinessException e) {\n    log.error(\"system call failed, raw resp={}\", resp, e);\n    throw e;\n}","handlingStrategy":"try-catch","validationCode":"JSONObject precheck = JSON.parseObject(resp);\nif (precheck.getInteger(\"code\") == null || precheck.getInteger(\"code\") != 0) {\n    log.error(\"downstream call will fail checkSystemCallResponse: code={}, message={}\",\n            precheck.getInteger(\"code\"), precheck.getString(\"message\"));\n}","typeGuard":null,"tryCatchPattern":"try {\n    Object data = CommonTool.checkSystemCallResponse(resp);\n} catch (BusinessException e) {\n    String remoteCode = e.getMessage();          // numeric remote code\n    log.error(\"system call rejected: remoteCode={}, raw={}\", remoteCode, resp, e);\n    throw new BusinessException(ResponseEnum.RESPONSE_FAILED, \"downstream system call failed: \" + remoteCode);\n}","preventionTips":["Always log the raw response string at the call site — the exception alone only carries the numeric code.","Pre-check resp for null/blank/invalid JSON before calling checkSystemCallResponse to avoid masking JSON errors as code!=0 flows.","Maintain a mapping of downstream error codes to actionable messages for the systems you call.","Add contract tests asserting code==0 envelopes from each integrated downstream service."],"tags":["http","remote-call","error-handling","fastjson","business-exception"],"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"}