调用京东商品详情 API 时，错误和异常处理是确保接口调用稳定性的关键环节。京东 API 的错误体系包括HTTP 状态码错误、业务错误码、网络异常等多种场景，需针对性设计处理逻辑。以下是系统化的错误处理方案：

一、错误类型与处理策略

京东商品详情 API（jingdong.item.read.get）的错误可分为三大类，处理方式各有不同：

错误类型	常见场景	处理核心
网络层异常	超时、连接失败、DNS 解析错误	重试机制 + 超时控制
HTTP 状态码错误	404（接口不存在）、500（服务器异常）	状态码判断 + 日志记录
业务错误码（核心）	10003（无权限）、20002（参数错误）、30001（频率超限）	错误码解析 + 针对性处理（如权限申请、参数修正）

二、网络层异常处理

网络波动是常见问题，需通过 “超时控制 + 重试机制” 保障稳定性。

1. 超时控制

京东 API 对响应速度有要求，设置合理超时时间（建议 3-5 秒），避免请求长期阻塞：

python

运行

# 设置连接超时和读取超时
response = requests.get(
    url, 
    params=params, 
    timeout=(3, 5)  # 连接超时3秒，读取超时5秒
)

2. 重试机制

对临时网络错误（如ConnectionError、Timeout），实现有限次数重试，但需注意：

• 幂等性判断：商品详情查询是幂等接口（重复调用结果一致），可安全重试；
• 重试间隔：使用指数退避策略（如 1s→2s→4s），避免加重服务器负担。

python

运行

from requests.exceptions import RequestException
import time

def safe_request(url, params, max_retries=3):
    retries = 0
    while retries < max_retries:
        try:
            response = requests.get(url, params=params, timeout=(3, 5))
            return response
        except RequestException as e:
            retries += 1
            if retries >= max_retries:
                raise Exception(f"网络请求失败（已重试{max_retries}次）：{str(e)}")
            # 指数退避等待
            time.sleep(2 **retries)
            print(f"第{retries}次重试...")

三、HTTP 状态码错误处理

京东 API 网关会返回标准 HTTP 状态码，需捕获并处理常见错误：

python

运行

response = safe_request(url, params)

# 处理HTTP状态码错误
if response.status_code != 200:
    error_msg = f"HTTP错误：状态码{response.status_code}，响应内容：{response.text}"
    # 区分不同状态码
    if response.status_code == 404:
        error_msg += "（可能是API路径错误，请检查base_url）"
    elif response.status_code == 500:
        error_msg += "（服务器内部错误，建议稍后重试）"
    elif response.status_code == 403:
        error_msg += "（IP被封禁，检查调用频率或联系京东开放平台）"
    raise Exception(error_msg)

四、业务错误码处理（核心）

京东 API 的业务错误通过返回体中的error_response字段描述，包含code（错误码）和zh_desc（中文描述），需针对高频错误码设计处理逻辑。

1. 错误码解析框架

python

运行

def handle_business_error(response_json):
    # 检查是否存在业务错误
    if "error_response" in response_json:
        error = response_json["error_response"]
        code = error["code"]
        msg = error.get("zh_desc", "未知错误")
        error_info = f"业务错误（code={code}）：{msg}"
        
        # 针对具体错误码处理
        if code == 10003:
            # 无权限访问：提示申请权限
            error_info += "（请在京东开放平台申请该接口权限）"
        elif code == 20002:
            # 参数错误：检查sku_id是否有效
            error_info += "（可能是sku_id不存在或格式错误）"
        elif code == 30001:
            # 调用频率超限：提示控制速度
            error_info += "（已超过接口调用频率限制，建议降低调用速度）"
        elif code == 10013:
            # 签名错误：检查签名生成逻辑
            error_info += "（签名计算错误，请检查appsecret和参数排序）"
        elif code == 40001:
            # 商品不存在：sku_id无效
            error_info += "（该sku_id对应的商品已下架或不存在）"
        
        raise Exception(error_info)

2. 常见错误码及解决方案

错误码	描述	解决方案
10003	没有权限访问该接口	在京东开放平台 “接口管理” 中申请权限
20002	参数错误	检查sku_id是否为有效数字（如 1000123456）
30001	调用频率超限	控制调用速度（个人开发者通常限 2 次 / 秒）
10013	签名错误	重新核对签名生成逻辑（参数排序、大小写）
40001	商品不存在或已下架	更换有效sku_id（通过京东商品页确认）
50002	系统繁忙	等待 1-2 秒后重试

五、完整错误处理示例

整合上述逻辑，形成完整的异常处理流程：

python

运行

import requests
import hashlib
import time
import json
from requests.exceptions import RequestException

class JDItemAPI:
    def __init__(self, app_key, app_secret):
        self.app_key = app_key
        self.app_secret = app_secret
        self.base_url = "https://api.jd.com/routerjson"

    def generate_sign(self, params):
        sorted_params = sorted(params.items(), key=lambda x: x[0])
        sign_str = "&".join([f"{k}={v}" for k, v in sorted_params])
        sign_str = self.app_secret + sign_str + self.app_secret
        return hashlib.md5(sign_str.encode()).hexdigest().lower()

    def safe_request(self, params, max_retries=3):
        """带重试的网络请求"""
        retries = 0
        while retries < max_retries:
            try:
                response = requests.get(
                    self.base_url,
                    params=params,
                    timeout=(3, 5)
                )
                # 处理HTTP状态码错误
                if response.status_code != 200:
                    raise Exception(f"HTTP错误：{response.status_code}，内容：{response.text}")
                return response.json()
            except RequestException as e:
                retries += 1
                if retries >= max_retries:
                    raise Exception(f"网络请求失败（重试{max_retries}次）：{str(e)}")
                time.sleep(2** retries)  # 指数退避
            except Exception as e:
                raise e

    def handle_business_error(self, response_json):
        """处理业务错误码"""
        if "error_response" in response_json:
            error = response_json["error_response"]
            code = error["code"]
            msg = error.get("zh_desc", "未知错误")
            error_map = {
                10003: "无权限（请申请接口权限）",
                20002: "参数错误（检查sku_id）",
                30001: "频率超限（降低调用速度）",
                10013: "签名错误（检查签名逻辑）",
                40001: "商品不存在（更换sku_id）"
            }
            detail = error_map.get(code, "")
            raise Exception(f"业务错误（code={code}）：{msg} {detail}")

    def get_item_detail(self, sku_id):
        """获取商品详情（带完整错误处理）"""
        try:
            params = {
                "app_key": self.app_key,
                "method": "jingdong.item.read.get",
                "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
                "format": "json",
                "v": "2.0",
                "sku_id": str(sku_id)  # 确保为字符串类型
            }
            params["sign"] = self.generate_sign(params)
            
            # 发送请求（含网络错误重试）
            response_json = self.safe_request(params)
            
            # 处理业务错误
            self.handle_business_error(response_json)
            
            # 提取商品数据
            return response_json["jingdong_item_read_get_response"]["result"]["item"]
        
        except Exception as e:
            print(f"调用失败：{str(e)}")
            return None

# 使用示例
if __name__ == "__main__":
    APP_KEY = "你的appkey"
    APP_SECRET = "你的appsecret"
    jd_api = JDItemAPI(APP_KEY, APP_SECRET)
    
    # 测试不同场景（正常/错误sku_id/无权限等）
    item = jd_api.get_item_detail(1000123456)  # 替换为实际sku_id
    if item:
        print(f"成功获取：{item['name']}，价格：{item['price']}")

六、进阶处理建议

1. 日志记录：对所有错误（含时间、参数、错误详情）记录到日志文件，方便问题追溯。
2. 监控告警：对高频错误（如频繁 500、签名错误）配置告警（企业微信 / 钉钉），及时发现配置问题。
3. 限流控制：本地维护调用计数器，严格控制每秒调用次数（如个人开发者≤2 次 / 秒），避免触发 30001 错误。
4. 动态降级：当 API 持续返回 500 错误时，临时切换到备用数据来源（如缓存），保障业务可用性。

通过以上处理，可有效应对京东 API 调用中的各类异常，提高接口稳定性和容错能力。核心原则是：分层处理（网络→HTTP→业务）、具体错误具体解决、关键操作留痕。