{"record":{"id":"a2629f33596033ba","repo":"iflytek/astron-agent","slug":"spark-api-image-param-error","errorCode":"SPARK_API_IMAGE_PARAM_ERROR","errorMessage":"SPARK_API_IMAGE_PARAM_ERROR","messagePattern":"SPARK_API_IMAGE_PARAM_ERROR","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/hub/src/main/java/com/iflytek/astron/console/hub/util/BotAIServiceClient.java","lineNumber":145,"sourceCode":"\n            MediaType jsonMediaType = MediaType.get(\"application/json; charset=utf-8\");\n            RequestBody requestBody = RequestBody.create(requestData.toString(), jsonMediaType);\n\n            Request request = new Request.Builder()\n                    .url(requestUrl)\n                    .post(requestBody)\n                    .build();\n\n            try (Response response = httpClient.newCall(request).execute()) {\n                int code = response.code();\n                ResponseBody responseBody = response.body();\n                if (responseBody == null) {\n                    throw new IllegalStateException(\"Image generation service response is empty\");\n                }\n\n                if (code == 401) {\n                    log.error(\"Image generation service authentication failed, user [{}]\", uid);\n                    throw new BusinessException(ResponseEnum.SPARK_API_IMAGE_PARAM_ERROR);\n                }\n\n                String responseBodyString = responseBody.string();\n                JSONObject result = JSONObject.parseObject(responseBodyString);\n\n                // Get error code from response\n                Integer responseCode = result.getJSONObject(\"header\").getInteger(\"code\");\n                if (responseCode == null) {\n                    responseCode = result.getIntValue(\"header.code\", -1);\n                }\n\n                log.info(\"Image generation request completed, user [{}], response code: {}\", uid, responseCode);\n\n                // Check if there is an error\n                if (responseCode != 0) {\n                    log.error(\"Image generation service returned error, user [{}], error code: {}\", uid, responseCode);\n\n                    // Convert error code to corresponding ResponseEnum and throw","sourceCodeStart":127,"sourceCodeEnd":163,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/hub/src/main/java/com/iflytek/astron/console/hub/util/BotAIServiceClient.java#L127-L163","documentation":"BotAIServiceClient.generateImage() throws SPARK_API_IMAGE_PARAM_ERROR when the iFlytek Spark image-generation HTTP endpoint returns status 401. Despite the 'param' name, this branch indicates authentication failure with the Spark open platform — the signed URL built from platformApiKey/platformApiSecret was rejected.","triggerScenarios":"Calling generateImage(uid, prompt, size) when the configured platform API key/secret are invalid, expired, revoked, or the request signature (buildAuthenticatedUrl) is malformed/mis-timed, causing HTTP 401 from the image service.","commonSituations":"Wrong or rotated API credentials in the platform account config (platformAccountService.requireIflytekOpenPlatform); expired Spark open-platform keys; server clock skew breaking the HMAC auth signature; missing/incorrect host configuration.","solutions":["Verify the iFlytek open-platform API key and secret in the platform account configuration and re-issue if expired","Confirm server clock is synchronized (NTP) since signed-URL auth is time-sensitive","Compare the generated auth URL construction against current Spark API docs (host, headers, signature algorithm)","Enable debug logging of the request (without leaking the key) and test the same credentials with a minimal Spark API call"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"PlatformAccountConfigDto.IflytekOpenPlatformConfig cfg = platformAccountService.requireIflytekOpenPlatform();\nif (cfg == null || StrUtil.isBlank(cfg.getPlatformApiKey()) || StrUtil.isBlank(cfg.getPlatformApiSecret())) {\n    throw new IllegalStateException(\"Spark open platform credentials missing or blank\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    botAIServiceClient.generateImage(uid, prompt, size);\n} catch (BusinessException e) {\n    if (\"SPARK_API_IMAGE_PARAM_ERROR\".equals(e.getCode())) {\n        // 401 from Spark: refresh/re-check platform API key & secret before retrying\n    } else throw e;\n}","preventionTips":["Rotate and verify Spark API keys/secrets in platform account config regularly","Keep server clocks NTP-synchronized for signed-URL auth","Monitor 401 rates on the Spark image endpoint as an early credential-expiry signal"],"tags":["authentication","spark-api","image-generation"],"backgroundTag":"authentication-required","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"}