如何在Python库中处理外部XML API返回的错误码？

你现在用RuntimeError统一抛出所有API错误的做法虽然简单，但确实不够灵活——用户没法精准区分不同类型的错误，调试和处理起来都很麻烦。咱们可以通过自定义异常类体系来改进这个问题，既保留API返回的所有错误元数据，又能让用户针对性地处理各类异常。

先回顾下你的场景：外部XML API出错时会返回带错误码、详细描述的响应，比如：

return (<Response Status="Failure" Action="LoadByName">
 <Error Message="WFP-00235 The job name does not exist in the database." ErrorCode="17" AtIndex="0"/>
)

当前你的处理逻辑大概是这样（补全了示例代码）：

import xml.etree.ElementTree as ElementTree

def parse_response(xml):
    root = ElementTree.fromstring(xml)
    if root.attrib.get("Status") == "Failure":
        error_elem = root.find("Error")
        error_msg = error_elem.attrib.get("Message")
        raise RuntimeError(error_msg)
    # 正常处理响应的逻辑...

改进方案：自定义异常类体系 #

首先定义一个基础异常类，所有API相关错误都继承它，然后根据你遇到的常见错误场景创建子类——这样用户既能统一捕获所有API错误，也能单独处理特定类型的问题：

class APIError(Exception):
    """基类：所有API相关错误的父类"""
    def __init__(self, message, error_code=None, action=None, at_index=None):
        super().__init__(message)
        # 保存API返回的所有元数据，方便用户调试
        self.error_code = error_code
        self.action = action
        self.at_index = at_index

# 根据业务场景定义具体异常子类
class InvalidCredentialsError(APIError):
    """用户名/密码无效时抛出"""
    pass

class ResourceNotFoundError(APIError):
    """请求的资源（如任务）不存在时抛出"""
    pass

class InvalidXMLError(APIError):
    """提交的XML格式错误时抛出"""
    pass

class ReadOnlyAttributeError(APIError):
    """尝试修改只读属性时抛出"""
    pass

接下来修改parse_response函数，根据API返回的错误码或消息内容，映射到对应的异常类：

def parse_response(xml):
    root = ElementTree.fromstring(xml)
    status = root.attrib.get("Status")
    action = root.attrib.get("Action")
    
    if status == "Failure":
        error_elem = root.find("Error")
        if not error_elem:
            raise APIError("API返回失败，但未提供具体错误信息")
        
        error_msg = error_elem.attrib.get("Message", "无错误描述")
        error_code = error_elem.attrib.get("ErrorCode")
        at_index = error_elem.attrib.get("AtIndex")
        
        # 转换错误码为整数（如果存在）
        error_code = int(error_code) if error_code else None
        
        # 优先用错误码匹配（如果API有明确的错误码规则）
        if error_code == 17:
            raise ResourceNotFoundError(error_msg, error_code, action, at_index)
        elif "invalid username" in error_msg.lower() or "invalid password" in error_msg.lower():
            raise InvalidCredentialsError(error_msg, error_code, action, at_index)
        elif "malformed xml" in error_msg.lower() or "invalid format" in error_msg.lower():
            raise InvalidXMLError(error_msg, error_code, action, at_index)
        elif "read-only" in error_msg.lower():
            raise ReadOnlyAttributeError(error_msg, error_code, action, at_index)
        else:
            # 未知错误，抛出基类APIError
            raise APIError(error_msg, error_code, action, at_index)
    
    # 正常处理响应的逻辑
    return root

这样做的好处 #

1. 语义清晰，便于调试：用户能通过异常类型直接判断错误原因，比如捕获ResourceNotFoundError就知道是请求的资源不存在了
2. 保留完整错误信息：异常实例里包含了错误码、操作类型、索引等所有API返回的元数据，用户可以用这些信息做更细致的处理
3. 灵活的异常捕获：用户可以选择统一捕获所有API错误，也只处理特定类型：

try:
    response = parse_response(api_response_xml)
except ResourceNotFoundError as e:
    print(f"找不到请求的资源：{e}（错误码：{e.error_code}）")
except InvalidCredentialsError:
    print("请检查你的用户名和密码是否正确")
except APIError as e:
    print(f"API请求出错：{e}")

进阶优化：用字典管理错误码映射 #

如果API有官方的错误码文档，建议把错误码和异常类的映射做成字典，这样后续维护更方便：

# 定义错误码到异常类的映射
ERROR_CODE_TO_EXCEPTION = {
    17: ResourceNotFoundError,
    401: InvalidCredentialsError,
    100: InvalidXMLError,
    200: ReadOnlyAttributeError,
    # 可以继续添加其他错误码
}

# 在parse_response里使用这个字典
if error_code in ERROR_CODE_TO_EXCEPTION:
    raise ERROR_CODE_TO_EXCEPTION[error_code](error_msg, error_code, action, at_index)
else:
    # 检查错误消息，或者直接抛出基类
    # ...

内容的提问来源于stack exchange，提问作者Stevoisiak