iflytek/astron-agent · error · ThirdPartyException

AIUI_RAGError

AIUI_RAGError

Error message

【url】{url}, reason {msg_json}

What it means

The shared AIUI request() helper in core/knowledge/infra/aiui/aiui.py raises ThirdPartyException(AIUI_RAGError) when the AIUI HTTP endpoint returns a non-success business payload. The exception message (f"【url】{url}, reason {msg_json}") is written to the log; the raised exception carries the parsed response body msg_json as its message. It is thrown both on the detected-error path and from a nested except Exception fallback around response handling.

Solutions

  1. Read msg_json in the exception message to get AIUI's own error code/description and address that root cause first.
  2. Verify AIUI credentials and assembled auth URL (assemble_auth_url) — invalid signatures commonly surface here.
  3. Confirm the docIds/repoIds passed (e.g. AIUI_QUERY_REPOID_V2 env) exist in the AIUI workspace.
  4. Add retry with backoff for transient AIUI 5xx/business errors, and log the full response body for diagnosis.

Example fix

// before
try:
    return await request(post_body, url)
except ThirdPartyException:
    raise
// after
try:
    return await request(post_body, url)
except ThirdPartyException as e:
    logger.warning("AIUI call failed, retrying: %s", e)
    await asyncio.sleep(1)
    return await request(post_body, url)
Defensive patterns

Strategy: try-catch

Validate before calling

assert os.getenv("AIUI_APP_ID") and os.getenv("AIUI_API_SECRET"), "AIUI credentials not configured"

Type guard

null

Try / catch

try:
    result = await chunk_query(...)
except ThirdPartyException as e:
    logger.error("AIUI business error: %s", e)
    # inspect e message for AIUI's own code/desc before deciding to retry

Prevention

When it happens

Trigger: Any AIUI call (chunk_query, document_parse, chunk_split, chunk_save, chunk_delete, get_doc_content) whose response body contains an error code/message instead of a success payload — e.g. AIUI auth failure, invalid app credentials, unknown docId/repoId, or AIUI-side service errors.

Common situations: Expired or wrong AIUI API key/secret in env config; querying docIds that were not ingested; AIUI returning HTML/error JSON that still parses; transient AIUI outage; the nested except Exception path converting any parsing hiccup into this same error.

Related errors

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

Appendix: source

Thrown at core/knowledge/infra/aiui/aiui.py:312

                        response_text = await response.text()
                        logger.info(
                            f"【url】:{url};Response 【XINGHUO-RAG】 body:{response_text}"
                        )
                        span_context.add_info_events({"AIUI_OUTPUT": response_text})
                        msg_json = json.loads(response_text)
                        try:
                            if msg_json["message"]["code"] == 0:
                                return msg_json["data"]

                            if msg_json["message"]["code"] == 1020:
                                return msg_json["data"]

                            error_msg = f"【url】{url}, reason {msg_json} "
                            logger.error(
                                f"{url} Failed to AIUI knowledge, err reason {error_msg}"
                            )

                            raise ThirdPartyException(
                                e=CodeEnum.AIUI_RAGError, msg=msg_json
                            )
                        except Exception:
                            raise ThirdPartyException(
                                e=CodeEnum.AIUI_RAGError, msg=msg_json
                            )

            except aiohttp.ClientError as e:
                logger.error(f"AIUI Network error: {e}")
                span_context.record_exception(e)
                raise ThirdPartyException(
                    e=CodeEnum.AIUI_RAGError, msg=f"AIUI Network error: {e}"
                ) from e

            except asyncio.TimeoutError as e:
                logger.error(f"AIUI Request timeout: {url}")
                span_context.record_exception(e)
                raise ThirdPartyException(

View on GitHub (pinned to 5e758547a8)