fiuai-sdk-python 0.11.9__tar.gz → 0.13.0__tar.gz

fiuai_sdk_python-0.13.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.13.0] - 2026-05-13
+
+### Fixed
+- `ApiError` 字段 (`code` / `type` / `message` / `detail` / `traceback`) 增加 `field_validator(mode="before")`, 对 frappe 偶发返回的 `list` / `dict` / `None` 类型自动规范化为 `str`, 修复 `ApiError.message=['Contract already exists']` 等 list 形态触发 Pydantic 校验失败导致 `parse_response` 整体崩溃的问题
+- `_normalize_error_dict` 入口对 `type` / `message` / `display_message` / `title` / `code` / `context` 同步用 `_to_text` 兜底规范化, 避免 `_MANDATORY_RE.match(...)` 在拿到非 str 时抛 `TypeError`
+- `parse_response` 加最外层 try/except 兜底, 任何未预期异常都返回结构化 `ApiResponse(error.code=SERVER_ERROR)`, 兑现"绝不抛异常"契约
+- `FiuaiSDK.get_user_profile_info` 解析失败分支错误地把 `str` 赋给 `ApiError` 字段、给没有 setter 的 deprecated property 赋值, 导致二次崩溃, 现改为构造 `ApiError(code=INTERNAL_VALIDATION_ERROR)` 写入 `error/errors`
+- `__version__` 与 `pyproject.toml` 版本号不一致 (`0.11.6` vs `0.12.0`) 统一为 `0.13.0`
+
+### Added
+- `FiuaiSDK._safe_request` 内部统一封装所有 `httpx` 调用, 捕获 `TimeoutException` / `RequestError` / 其他异常, 统一返回 `ApiResponse(error.code=NETWORK_ERROR)` 或 `SERVER_ERROR`, SDK 调用方不再需要捕获 httpx 异常
+- `resp._to_text` 公共兜底 helper, 把任意 (list / dict / None / 其他) 安全规范化为 str
+
+## [Unreleased]
+
+### Added
+- 新增结构化错误处理: `ApiError` model + `FiuaiErrorCode` 枚举
+  - `ApiError` 字段: `code` / `type` / `message` / `detail` / `context` / `http_status_code` / `traceback`
+  - `FiuaiErrorCode` 提供稳定错误码枚举 (跨语言/跨版本不变), 与 frappe 二开侧 codes.py 对齐
+- `ApiResponse` 新增字段:
+  - `error: ApiError | None` - 主错误 (errors[0] 规整后)
+  - `errors: list[ApiError]` - 所有错误项
+  - `warnings: list[str]` - 非错误的提示文案
+  - `raw: dict` - 原始 frappe response (调试用)
+- SDK 内置兜底解析器 `error_parsers.py`, 服务端没补 `errors[].context` 时自动从 frappe 异常字符串提取 doctype/name/fields
+- 网络层异常 (`response=None` / 非 JSON / 非 dict body) 也统一走 `ApiError`, code 为 `NETWORK_ERROR` / `API_INVALID_JSON` / `API_NO_RESPONSE`
+- frappe `messages[]` 中红色友好文案 (启发式: indicator=red / title=错误 / 文本以"错误:"开头 / raise_exception 标记) 自动合并到主 `ApiError.message`
+
+### Changed
+- `parse_response` 重写, 返回的 `ApiResponse` 始终包含结构化 `error` 字段, 一定不会抛异常
+- `_is_api_success` 修复: `data is None` 不再判失败, `delete` / `cancel` 等正常返回 None 的接口不会被误判
+
+### Deprecated
+- `ApiResponse.error_code` / `ApiResponse.error_message` 改为派生 property, 访问触发 `DeprecationWarning`
+  - 迁移路径:
+    - `resp.error_message[0]` → `resp.error.message`
+    - `resp.error_code[0]` → `resp.error.code`
+  - 下个 major 版本将移除
+
+### Removed
+- N/A
+
+### Fixed
+- `parse_response` 在 HTTP 502/504 等代理层 HTML 错误时不再 silent fallback, 返回 code=`API_INVALID_JSON` 的结构化 ApiError
+- `_extract_error_info` 中无意义的 try/except 包装移除
+
+### Security
+- N/A
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial release
+- Basic SDK structure and functionality

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fiuai_sdk_python
-Version: 0.11.9
+Version: 0.13.0
 Summary: FiuAI Python SDK - 企业级AI服务集成开发工具包
 Project-URL: Homepage, https://github.com/fiuai/fiuai-sdk-python
 Project-URL: Documentation, https://github.com/fiuai/fiuai-sdk-python#readme

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fiuai_sdk_python"
-version = "0.11.9"
+version = "0.13.0"
 description = "FiuAI Python SDK - 企业级AI服务集成开发工具包"
 readme = "README.md"
 requires-python = ">=3.12"

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.13.0}/src/fiuai_sdk_python/__init__.py

@@ -10,8 +10,15 @@ from .context import (
     is_current_context_valid,
     get_trace_id,
 )
+from .error_code import (
+    EXCEPTION_TO_CODE,
+    FiuaiErrorCode,
+    exception_to_code,
+    status_code_to_code,
+)
+from .resp import ApiError, ApiResponse, parse_response
 
-__version__ = "0.11.6"
+__version__ = "0.13.0"
 
 __all__ = [
     'FiuaiSDK',
@@ -25,4 +32,11 @@ __all__ = [
     'get_current_missing_fields',
     'is_current_context_valid',
     'get_trace_id',
+    'ApiError',
+    'ApiResponse',
+    'parse_response',
+    'FiuaiErrorCode',
+    'EXCEPTION_TO_CODE',
+    'exception_to_code',
+    'status_code_to_code',
 ]

fiuai_sdk_python-0.13.0/src/fiuai_sdk_python/_resp_helpers.py

@@ -0,0 +1,163 @@
+# -- coding: utf-8 --
+# Project: fiuai_sdk_python
+# Created Date: 2026-05-09
+# Author: liming
+# Email: lmlala@aliyun.com
+# Copyright (c) 2025 FiuAI
+
+"""
+resp.py 的内部 helper 集合.
+
+不是公开 API, 不要从外部直接 import. 拆出来仅为了控制 resp.py 行数 (单文件 < 400 行规约).
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from httpx import Response
+
+logger = logging.getLogger(__name__)
+
+
+# --------------------------------------------------------------------------
+# 响应体读取 (用于 JSON 解析失败时的日志/预览)
+# --------------------------------------------------------------------------
+
+
+def get_response_body_preview(response: Response, max_chars: int = 300) -> str:
+    """安全读取响应体前若干字符, 用于错误信息预览. 兼容编码问题及中文."""
+    try:
+        raw = response.content
+        if not raw:
+            return ""
+        text = raw.decode("utf-8", errors="replace").strip()
+        if len(text) > max_chars:
+            text = text[:max_chars] + "..."
+        return text
+    except Exception:
+        return ""
+
+
+def get_response_body_for_log(response: Response, max_chars: int = 2000) -> str:
+    """安全读取完整响应体用于日志, 避免编码异常, 支持中文."""
+    try:
+        raw = response.content
+        if not raw:
+            return "(empty)"
+        text = raw.decode("utf-8", errors="replace").strip()
+        if len(text) > max_chars:
+            text = text[:max_chars] + "...(truncated)"
+        return text
+    except Exception as ex:
+        return f"(decode error: {ex})"
+
+
+# --------------------------------------------------------------------------
+# 业务成功判定
+# --------------------------------------------------------------------------
+
+
+def is_api_success(response_data: Dict[str, Any]) -> bool:
+    """判断 API 业务是否成功.
+
+    与旧版的差异:
+    - 不再要求"必须有 data 才算成功". delete/cancel 等接口正常返回 None 不会被误判
+    - 仅依据 errors / exc / http_status_code (frappe 内嵌) 判定
+    """
+    if not isinstance(response_data, dict):
+        return False
+    if response_data.get("errors"):
+        return False
+    if response_data.get("exc"):
+        return False
+    inner_status = response_data.get("http_status_code")
+    if inner_status is not None:
+        try:
+            return 200 <= int(inner_status) < 300
+        except (TypeError, ValueError):
+            return False
+    return True
+
+
+def extract_success_data(response_data: Dict[str, Any]) -> Any:
+    """从成功响应中提取数据. 优先 data 字段, 其次 messages 字段."""
+    data = response_data.get("data")
+    if data is not None:
+        return data
+    messages = response_data.get("messages")
+    if messages is not None:
+        return messages
+    return None
+
+
+# --------------------------------------------------------------------------
+# messages 红色 / warning 启发式分流
+# --------------------------------------------------------------------------
+
+
+_RED_INDICATOR = "red"
+_ERROR_TITLES = {"错误", "Error", "ERROR"}
+# frappe _get_missing_mandatory_fields() 等默认友好文案的前缀, 用于启发式判定:
+# "Error: Value missing for ..." / "错误: ..." / "错误：..." (中文全角冒号)
+_ERROR_TEXT_PREFIXES = ("错误:", "错误：", "Error:", "ERROR:", "error:")
+
+
+def _is_error_message(msg: Dict[str, Any]) -> bool:
+    """判定一条 message 是否是错误补充文案 (vs 普通提示).
+
+    frappe 在调用 ``frappe.throw`` / ``MandatoryError`` 时, 默认 msgprint 不设
+    indicator 也不设 title, 但 message 文本本身会以 ``错误:`` / ``Error:`` 开头.
+    所以判定要走多重启发式:
+    1. ``indicator == "red"``
+    2. ``title in {"错误", "Error", "ERROR"}``
+    3. ``raise_exception`` 标记
+    4. message 文本以错误前缀开头
+    """
+    if (msg.get("indicator") or "").strip().lower() == _RED_INDICATOR:
+        return True
+    if (msg.get("title") or "").strip() in _ERROR_TITLES:
+        return True
+    if msg.get("raise_exception"):
+        return True
+    text = (msg.get("message") or "").strip()
+    return text.startswith(_ERROR_TEXT_PREFIXES)
+
+
+def split_messages(raw_messages: Any) -> tuple[List[str], List[str]]:
+    """把 frappe messages[] 拆成 (error_texts, warning_texts).
+
+    判定基于 ``_is_error_message`` 多重启发式 (indicator=red / title=错误 / message
+    文本以 "错误:" / "Error:" 开头 / raise_exception 标记). 命中即归错误文案,
+    否则进 warnings.
+    """
+    error_texts: List[str] = []
+    warnings: List[str] = []
+    if not isinstance(raw_messages, list):
+        return error_texts, warnings
+
+    for msg in raw_messages:
+        if not isinstance(msg, dict):
+            text = str(msg).strip()
+            if text:
+                warnings.append(text)
+            continue
+        text = (msg.get("message") or "").strip()
+        if not text:
+            continue
+        if _is_error_message(msg):
+            error_texts.append(text)
+        else:
+            warnings.append(text)
+
+    return error_texts, warnings
+
+
+def merge_error_message(primary: str, extras: List[str]) -> str:
+    """把 frappe messages 里的友好文案合并到主错误 message, 去重去空."""
+    pieces: List[str] = []
+    if primary:
+        pieces.append(primary)
+    for extra in extras:
+        if extra and extra not in pieces:
+            pieces.append(extra)
+    return "; ".join(pieces)

{fiuai_sdk_python-0.11.9 → fiuai_sdk_python-0.13.0}/src/fiuai_sdk_python/client.py

@@ -10,7 +10,8 @@ from logging import getLogger
 from .type import UserProfile
 from .profile import UserProfileInfo
 from .auth import AuthHeader
-from .resp import parse_response, ApiResponse
+from .resp import ApiError, ApiResponse, _build_network_error_response, parse_response
+from .error_code import FiuaiErrorCode
 from .context import get_current_headers
 
 
@@ -220,11 +221,12 @@ class FiuaiSDK(object):
    
     def get_avaliable_company(self, page: int=1, page_size: int=20, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        r = self.client.get(self.url + "/api/method/fiuai.network.doctype.company.company.get_available_companies", 
-                           params={"page": page, "page_size": page_size}, 
-                           headers=headers)
-        
-        return self.post_process(r)
+        return self._safe_request(
+            "GET",
+            self.url + "/api/method/fiuai.network.doctype.company.company.get_available_companies",
+            params={"page": page, "page_size": page_size},
+            headers=headers,
+        )
     
     def swith_company(self, tenant: str = "", company: str = "") -> ApiResponse:
 
@@ -266,37 +268,60 @@ class FiuaiSDK(object):
             user_id = self.headers.x_fiuai_user
 
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + f"/api/v2/internal/user/profile/{user_id}", headers=headers)
-
-        profile_response = self.post_process(res)
+        profile_response = self._safe_request(
+            "GET",
+            self.url + f"/api/v2/internal/user/profile/{user_id}",
+            headers=headers,
+        )
 
-        if profile_response.is_success():
-            try:
-                profile_response.data = UserProfileInfo.model_validate(profile_response.data)
-            except Exception as e:
-                profile_response.error = str(e)
-                profile_response.error_code = "PROFILE_FORMAT_ERROR"
-                return profile_response
-            return profile_response
-        else:
+        if not profile_response.is_success():
             return profile_response
 
+        try:
+            profile_response.data = UserProfileInfo.model_validate(profile_response.data)
+        except Exception as e:
+            logger.warning("UserProfileInfo parse failed for user=%s: %s", user_id, e)
+            err = ApiError(
+                code=FiuaiErrorCode.INTERNAL_VALIDATION_ERROR.value,
+                type="ProfileFormatError",
+                message="用户信息格式异常，请联系管理员",
+                detail=str(e),
+                http_status_code=profile_response.status_code,
+            )
+            profile_response.api_success = False
+            profile_response.error = err
+            profile_response.errors = [err]
+            profile_response.data = None
+        return profile_response
+
 
    
     def internal_post_req(self, uri, postdata={}, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/' + uri.lstrip('/'), data=postdata, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/' + uri.lstrip('/'),
+            data=postdata,
+            headers=headers,
+        )
 
     def internal_get_req(self, uri, params={}, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/' + uri.lstrip('/'), params=params, headers=headers)
-        return self.post_process(res)
-    
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/' + uri.lstrip('/'),
+            params=params,
+            headers=headers,
+        )
+
     def internal_create(self, data={}, auto_submit: bool = False, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/create', data={"data":json.dumps(data, ensure_ascii=False), "auto_submit": auto_submit}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/create',
+            data={"data": json.dumps(data, ensure_ascii=False), "auto_submit": auto_submit},
+            headers=headers,
+        )
 
     def internal_get(self, doctype, name, fields=None, filters=None, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         d = {
@@ -308,8 +333,12 @@ class FiuaiSDK(object):
         if filters:
             d["filters"] = json.dumps(filters)
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/doctype/get', params=d, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/doctype/get',
+            params=d,
+            headers=headers,
+        )
 
     def get_decrypted_password(
         self,
@@ -321,12 +350,12 @@ class FiuaiSDK(object):
         """从 Frappe __Auth 读取 Password 类型字段明文 (internal get_password)."""
         params = {"doctype": doctype, "name": name, "fieldname": fieldname}
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(
+        resp = self._safe_request(
+            "GET",
             self.url + "/api/v2/internal/doctype/get_password",
             params=params,
             headers=headers,
         )
-        resp = self.post_process(res)
         if resp.is_success() and resp.data and isinstance(resp.data, dict):
             pw = resp.data.get("password")
             return pw if isinstance(pw, str) else None
@@ -346,76 +375,169 @@ class FiuaiSDK(object):
         if order_by:
             d["order_by"] = order_by
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(
-            self.url + '/api/v2/internal/doctype/get_list', 
-            params=d, 
-            headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/doctype/get_list',
+            params=d,
+            headers=headers,
+        )
 
-    
     def internal_update(self, data={}, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/update', data={"data":json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/update',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
     def internal_delete(self, doctype, name, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/delete', data={"doctype": doctype, "name":name}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/delete',
+            data={"doctype": doctype, "name": name},
+            headers=headers,
+        )
 
     def internal_submit(self, doctype, name, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/submit', data={"doctype": doctype, "name":name}, headers=headers)
-        return self.post_process(res)
-    
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/submit',
+            data={"doctype": doctype, "name": name},
+            headers=headers,
+        )
+
     def internal_cancel(self, doctype, name, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/doctype/cancel', data={"doctype": doctype, "name":name}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/doctype/cancel',
+            data={"doctype": doctype, "name": name},
+            headers=headers,
+        )
 
 
     ######## 特殊接口 ########
     def get_meta(self, doctype: str, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/doctype/meta/' + doctype, headers=headers)
-      
-        return self.post_process(res)
-    
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/doctype/meta/' + doctype,
+            headers=headers,
+        )
 
     def get_ontology_event(self, event_id: str, extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.get(self.url + '/api/v2/internal/ontology/event/' + event_id, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/ontology/event/' + event_id,
+            headers=headers,
+        )
 
     def get_ontology_event_list(self, event_filter: Dict[str, Any], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
-
         headers = self._get_merged_headers(extra_headers)
-
-        ### url encode 可能 的 list 或者 dict 值
-        
-
-        res = self.client.get(self.url + '/api/v2/internal/ontology/event', params={"event_filter": quote(json.dumps(event_filter, ensure_ascii=False))}, headers=headers)
-      
-        return self.post_process(res)
+        return self._safe_request(
+            "GET",
+            self.url + '/api/v2/internal/ontology/event',
+            params={"event_filter": quote(json.dumps(event_filter, ensure_ascii=False))},
+            headers=headers,
+        )
 
     def add_ontology_event(self, data: Dict[str, Any], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/ontology/event/add', data={"data": json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/ontology/event/add',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
     def update_ontology_event(self, data: Dict[str, Any], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
-
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/ontology/event', data={"data": json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/ontology/event',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
     def batch_add_ontology_event(self, data: List[Dict[str, Any]], extra_headers: Optional[Dict[str, Any]] = None) -> ApiResponse:
         headers = self._get_merged_headers(extra_headers)
-        res = self.client.post(self.url + '/api/v2/internal/ontology/event/batch_add', data={"data": json.dumps(data, ensure_ascii=False)}, headers=headers)
-        return self.post_process(res)
+        return self._safe_request(
+            "POST",
+            self.url + '/api/v2/internal/ontology/event/batch_add',
+            data={"data": json.dumps(data, ensure_ascii=False)},
+            headers=headers,
+        )
 
    
     ######## 数据处理 ########
+    def _safe_request(self, method: str, url: str, **kwargs) -> ApiResponse:
+        """统一的 HTTP 请求封装, 兜底捕获 httpx 网络异常.
+
+        SDK 对外契约: 永远返回 ``ApiResponse``, 不抛 httpx 异常. 调用方只需读
+        ``resp.is_success()`` / ``resp.error.code`` 即可分流业务/网络错误.
+
+        Args:
+            method: HTTP 方法, "GET" / "POST" (大小写不敏感)
+            url: 完整请求 URL
+            **kwargs: 透传给 ``httpx.Client.{get,post}`` 的参数
+
+        Returns:
+            ApiResponse: 结构化响应. 网络异常时 ``error.code`` 为
+            ``NETWORK_ERROR`` / ``SERVER_ERROR``.
+        """
+        method_upper = method.upper()
+        try:
+            if method_upper == "GET":
+                res = self.client.get(url, **kwargs)
+            elif method_upper == "POST":
+                res = self.client.post(url, **kwargs)
+            else:
+                logger.error("Unsupported HTTP method: %s", method)
+                return _build_network_error_response(
+                    code=FiuaiErrorCode.SERVER_ERROR,
+                    message=f"Unsupported HTTP method: {method}",
+                    status_code=500,
+                    http_success=False,
+                )
+        except httpx.TimeoutException as e:
+            logger.warning("HTTP timeout: %s %s, detail=%s", method_upper, url, e)
+            return _build_network_error_response(
+                code=FiuaiErrorCode.NETWORK_ERROR,
+                message="请求超时，请稍后重试",
+                status_code=504,
+                http_success=False,
+                detail=str(e),
+            )
+        except httpx.RequestError as e:
+            logger.warning(
+                "HTTP request error: %s %s, type=%s, detail=%s",
+                method_upper,
+                url,
+                type(e).__name__,
+                e,
+            )
+            return _build_network_error_response(
+                code=FiuaiErrorCode.NETWORK_ERROR,
+                message=f"网络异常: {type(e).__name__}",
+                status_code=502,
+                http_success=False,
+                detail=str(e),
+            )
+        except Exception as e:
+            logger.exception("Unexpected HTTP error: %s %s", method_upper, url)
+            return _build_network_error_response(
+                code=FiuaiErrorCode.SERVER_ERROR,
+                message="请求执行异常",
+                status_code=500,
+                http_success=False,
+                detail=str(e),
+            )
+        return self.post_process(res)
+
     def post_process(self, response) -> ApiResponse:
         """
         处理API响应，使用结构化的错误处理系统