10001 · API Key无效或已过期 认证

错误描述：调用时使用的 API Key 未注册、已被吊销或已超出有效期限。

影响范围：所有 API 调用均会失败。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 10001,
    "message": "API Key无效或已过期",
    "data": {
      "detail": "当前密钥已过期，过期时间：2026-06-12",
      "request_id": "req_b2c3d4e5f6"
    }
  }
}

排查步骤：

1. 检查 HTTP Header 中 X-API-Key 的值是否正确填写
2. 确认 API Key 是否在有效期内（查看购买记录中的到期时间）
3. 若使用环境变量配置密钥，确认环境变量是否正确加载

解决方案：

1. 如 Key 已过期：在蓝鲸选品平台续费或购买新套餐
2. 更新代码或配置文件中的密钥为最新值

预防措施：

• 定时调用 myUsage 接口（免费接口）监控套餐到期时间
• 在套餐到期前至少 7 天续费，避免服务中断

10002 · 请求签名验证失败 认证

错误描述：请求的签名校验未通过，可能因请求被篡改或签名算法不匹配。

影响范围：单次请求失败。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 10002,
    "message": "请求签名验证失败",
    "data": {
      "detail": "签名不匹配，请检查签名参数",
      "request_id": "req_c3d4e5f6g7"
    }
  }
}

排查步骤：

1. 确认是否修改过请求体内容（签名基于请求体计算）
2. 检查客户端时间是否与服务端同步（时间偏差会导致签名失效）

解决方案：

1. 用官方文档中的签名示例重新生成签名
2. 同步本地系统时间（推荐使用 NTP 自动同步）

预防措施：确保服务器时间通过 NTP 自动同步。

10003 · 账户权限不足，无法访问该资源 权限

错误描述：当前 API Key 对应的套餐或账户等级无权访问请求的资源。

影响范围：特定接口或站点数据不可用。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 10003,
    "message": "账户权限不足，无法访问该资源",
    "data": {
      "detail": "当前套餐不支持站点 MLB 的数据查询",
      "request_id": "req_d4e5f6g7h8"
    }
  }
}

排查步骤：

1. 调用 myUsage 接口查看当前套餐信息及支持的站点/功能范围
2. 确认请求的资源是否超出套餐范围

解决方案：

1. 升级套餐以获取更多站点或功能权限
2. 或调整查询参数，仅访问当前套餐支持的数据范围

预防措施：购买套餐前确认所需站点和功能清单。

20001 · 缺少必填参数 [参数名] 参数

错误描述：接口调用时未传入某个必填参数。

影响范围：单次请求失败。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 20001,
    "message": "缺少必填参数 [siteId]",
    "data": {
      "detail": "请传入站点ID参数，可选值：MLM(墨西哥), MLB(巴西), MLA(阿根廷), MLC(智利)",
      "request_id": "req_e5f6g7h8i9"
    }
  }
}

排查步骤：

1. 核对接口文档确认所有必填参数
2. 检查 JSON 请求体中 arguments 对象是否完整

正确请求示例：

// 查询商品信息 — siteId 和 itemId 均为必填
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "itemInfo",
    "arguments": {
      "siteId": "MLM",              // 必填：站点ID
      "itemId": "MLM1602785195"      // 必填：商品ID
    }
  }
}

常见接口必填参数速查：

解决方案：根据错误提示补全缺失的参数后重新请求。

预防措施：在代码中增加参数完整性校验，调用前检查必填字段。

20002 · 参数 [参数名] 格式错误 参数

错误描述：传入的参数值不符合要求的格式（如类型错误、长度超限）。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 20002,
    "message": "参数 [pageSize] 格式错误",
    "data": {
      "detail": "pageSize 应为整数类型",
      "request_id": "req_f6g7h8i9j0"
    }
  }
}

排查步骤：

1. 确认参数类型是否正确（如 pageNo 为整数，itemId 为字符串）
2. 检查 JSON 中参数值是否携带了引号（如 "pageSize": "20" 应为 "pageSize": 20）

正确请求示例：

// 类型正确 ✅
{
  "name": "itemSearch",
  "arguments": {
    "siteId": "MLM",
    "title": "peluche",
    "pageSize": 20        // 整数
  }
}

// 类型错误 ❌
{
  "name": "itemSearch",
  "arguments": {
    "siteId": "MLM",
    "title": "peluche",
    "pageSize": "20"      // 字符串 → 应传整数
  }
}

解决方案：按接口要求的参数类型修正后重试。

预防措施：开发时参考接口的 inputSchema 定义，确保参数类型匹配。

20003 · 参数 [参数名] 值超出允许范围 参数

错误描述：参数值超过了接口允许的范围（如页码过大、价格超出限制）。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 20003,
    "message": "参数 [pageSize] 值超出允许范围",
    "data": {
      "detail": "pageSize 允许范围为 1-100，传入值：500",
      "request_id": "req_g7h8i9j0k1"
    }
  }
}

排查步骤：确认传入值是否在接口允许的范围内。

常见参数允许范围：

解决方案：调整参数值到允许范围内后重试。

预防措施：调用前对参数值做范围校验。

30001 · 商品ID不存在 数据

错误描述：查询的商品 ID 在指定站点中不存在或已被删除。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 30001,
    "message": "商品ID不存在",
    "data": {
      "detail": "在站点 MLM 中未找到商品 MLM9999999999",
      "request_id": "req_h8i9j0k1l2"
    }
  }
}

排查步骤：

1. 确认商品 ID 前缀与站点对应（MLM = 墨西哥, MLB = 巴西, MLA = 阿根廷, MLC = 智利）
2. 在 Mercado Libre 网站直接搜索该商品 ID 验证是否存在
3. 确认商品未被下架或删除（itemInfo 会返回状态）

解决方案：核实正确的商品 ID 后重试。

预防措施：在查询前通过 itemSearch 或 catalogSearch 确认商品有效。

30002 · 类目ID无效或已变更 数据

错误描述：传入的类目 ID 不存在、已废弃或在当前站点无效。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 30002,
    "message": "类目ID无效或已变更",
    "data": {
      "detail": "MLM999999 在当前站点中不存在",
      "request_id": "req_i9j0k1l2m3"
    }
  }
}

排查步骤：

1. 使用 categorySearch 接口按关键词搜索类目
2. 确认类目 ID 属于当前查询的站点（不同站点的类目 ID 体系独立）

解决方案：通过 categorySearch 获取正确的类目 ID。

预防措施：定期重新拉取类目列表，避免长期硬编码类目 ID。

30003 · 查询结果为空 数据

错误描述：根据当前筛选条件未找到任何数据。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 30003,
    "message": "查询结果为空",
    "data": {
      "detail": "当前筛选条件下未找到匹配的商品",
      "request_id": "req_j0k1l2m3n4"
    }
  }
}

排查步骤：

1. 逐步放宽筛选条件（如扩大价格范围、降低销量门槛）
2. 确认关键词拼写是否正确（建议用西语或葡语关键词）

解决方案：调整搜索条件后重试。

预防措施：先使用较宽泛的条件搜索确定数据存在，再逐步精确筛选。

30004 · 返回数据量超过最大限制 数据

错误描述：查询结果数量超过接口单次返回上限。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 30004,
    "message": "返回数据量超过最大限制",
    "data": {
      "detail": "当前限制：1000条，请缩小查询范围或分批查询",
      "request_id": "req_k1l2m3n4o5"
    }
  }
}

排查步骤：评估当前筛选条件是否过于宽泛。

解决方案：

1. 添加更精确的筛选条件（缩小价格区间、指定类目等）
2. 使用 pageNo 和 pageSize 分页逐批获取

预防措施：始终使用分页参数，每页建议 20-50 条。

40002 · 月调用量超出套餐限制 速率

错误描述：当月累计调用次数已超出套餐额度。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 40002,
    "message": "月调用量超出套餐限制",
    "data": {
      "detail": "当前套餐月额度：24000次，已使用：24000次",
      "reset_time": "下月重置",
      "request_id": "req_m3n4o5p6q7"
    }
  }
}

限流策略说明：

恢复机制：

1. 等待次月额度重置
2. 或升级套餐获取更高调用额度

排查步骤：

1. 调用 myUsage 接口查看当前套餐剩余次数
2. 评估当前用量是否超过日常平均水平

解决方案：

1. 升级套餐提高月额度
2. 优化调用策略，缓存重复查询的结果

预防措施：

• 每次启动批量任务前调用 myUsage 检查剩余额度
• 对高频查询的数据（如类目统计）做本地缓存（建议缓存时间 ≥ 1 小时）
• 设置调用量告警阈值（如达到额度的 80% 时通知）

50001 · MCP服务暂时不可用 服务端

错误描述：服务端因维护或故障暂时无法处理请求。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 50001,
    "message": "MCP服务暂时不可用",
    "data": {
      "detail": "服务正在维护中，预计 2026-07-08 12:00 UTC 恢复",
      "request_id": "req_n4o5p6q7r8"
    }
  }
}

排查步骤：

1. 使用 curl 直接测试端点连通性
2. 稍等 1-2 分钟后重试（排除临时网络抖动）
3. 确认本地网络能否解析 xpagent.lingdongsz.com

curl 连通性测试：

curl -s -o /dev/null -w "HTTP %{http_code}" \
  "https://xpagent.lingdongsz.com/mcp-servers/xprpc" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# 预期返回 HTTP 200

解决方案：等待服务恢复后重试。如持续不可用，联系技术支持。

预防措施：在代码中实现退避重试逻辑（推荐：3 次重试，间隔 1s/3s/5s）。

50002 · 请求超时 服务端

错误描述：服务端在指定时间内未能完成请求处理。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 50002,
    "message": "请求超时",
    "data": {
      "detail": "超时时间：30s，建议缩小查询范围后重试",
      "request_id": "req_o5p6q7r8s9"
    }
  }
}

排查步骤：

1. 检查是否一次查询的数据范围过大（如全站类目搜索）
2. 确认本地网络延迟是否正常

解决方案：

1. 缩小查询范围（如缩短时间区间、减少类目范围）
2. 拆分大数据查询为多个小查询
3. 设置更长的客户端超时时间（建议 ≥ 60s）

预防措施：复杂查询先用小范围参数测试响应时间，再逐步扩大。

50003 · 数据源服务异常 服务端

错误描述：底层数据源（Mercado Libre API）暂时不可用或返回异常。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 50003,
    "message": "数据源服务异常",
    "data": {
      "detail": "Mercado Libre API 暂时不可用，请稍后重试",
      "request_id": "req_p6q7r8s9t0"
    }
  }
}

排查步骤：

1. 直接访问 Mercado Libre 网站确认数据源是否正常
2. 调用其他蓝鲸选品接口判断是局部还是全局问题

解决方案：等待数据源恢复后重试，通常 5-15 分钟内自动恢复。

预防措施：关键任务建议避开 Mercado Libre 数据维护时段（详见 FAQ）。

60001 · 筛选条件冲突 业务

错误描述：同时传入了互斥的筛选参数，导致无法执行查询。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 60001,
    "message": "筛选条件冲突",
    "data": {
      "detail": "参数 hisVolStart 与 sales30VolStart 不可同时使用",
      "request_id": "req_q7r8s9t0u1"
    }
  }
}

排查步骤：查阅文档确认各参数之间的兼容性关系。

解决方案：移除冲突参数，保留需要的筛选条件后重试。

已知互斥参数组合：

预防措施：调用前确认筛选条件是否有冲突，每次查询使用单个筛选维度。

60002 · 数据源暂时不可用，请稍后重试 业务

错误描述：蓝鲸选品的数据同步或缓存服务临时异常。

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 60002,
    "message": "数据源暂时不可用，请稍后重试",
    "data": {
      "detail": "数据同步中，预计 5 分钟后恢复",
      "request_id": "req_r8s9t0u1v2"
    }
  }
}

排查步骤：

1. 确认是偶发还是持续性问题（重试 1-2 次）
2. 检查蓝鲸选品服务是否有维护公告

解决方案：等待 5-10 分钟后重试。

预防措施：对实时性要求不高的查询，尽量安排在非高峰时段执行。