跳转到主要内容

错误响应#

HTTP 状态码	含义	建议操作
`400 Bad Request`	请求体或查询参数无效。	修正请求后重试。
`401 Unauthorized`	缺少凭据、凭据无效、已过期或未激活。	检查认证请求头或联系 Ideal House。
`403 Forbidden`	所请求的 `shopId` 与凭据不关联。	使用分配给凭据的 Shop ID。
`404 Not Found`	无导入状态或匹配的商品。	验证 Shop ID 和所请求的商品 ID 或 SKU。
`409 Conflict`	该店铺已有其他活跃的导入任务。	等待当前导入任务完成。
`429 Too Many Requests`	请求速率过高。	使用指数退避加随机抖动进行重试。
`500 Internal Server Error`	服务遇到意外错误。	使用指数退避重试。若错误持续，请联系 Ideal House。
`502 Bad Gateway` 或 `503 Service Unavailable`	API 暂时不可用。	使用指数退避重试。

验证错误可能采用以下格式：

json

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

message 中的文本可能有所不同。请使用 HTTP 状态码和文档化的响应字段进行程序逻辑处理。

重试与恢复指南#

当任务处于 pending 或 running 状态时，每 2 至 5 秒轮询一次。
对于 429、500、502 和 503 响应，使用带随机抖动的指数退避，并设置最大重试次数上限。
不要自动重试 400、401 或 403 响应，除非已修正请求或凭据。
遇到 409 后，等待活跃任务达到 completed 或 failed 状态。
如果提交在收到响应前超时，请在重新提交批次前先查询状态端点。
使用相同的 SKU 重试同一商品是安全的，因为导入操作采用创建或更新行为。
对于包含商品级失败项的已完成任务，提交仅包含失败商品的新批次。
任务级失败后，successCount 中计数的商品可能已被更新。使用相同 SKU 重新提交原始批次是安全的。
即使请求返回 503，删除操作可能已经生效。重试同一删除请求是安全的。

状态端点用于跟踪当前活跃或最近的任务，而非永久性的导入历史记录。请将提交的批次、jobId、状态响应和最终结果存储在您自己的系统中，以便对账和支持。

生产环境清单#

将 Client Secret 存储在密钥管理器或受保护的服务器环境中。
为每个商品使用稳定且唯一的 SKU。
每次请求发送的商品不超过 500 个。
确保图片 URLs 可公开访问，并在处理期间保持可用。
仅在需要图片预处理且接受相关的 1 积分/张图片处理费用时才显式设置 processImages: true。否则请省略或将其设置为 false。
仅当同时设置 processImages 和 processFloorImages 为 true 时启用地板图片分割。
为每个商品提供 name、imageUrl、productUrl、width、height 及一个受支持的 productType。
若提供，将 status 设置为 active、inactive、out_of_stock 或 invalid。
尺寸以正值提供并附带支持的单位，或省略单位以使用英寸；存储值会标准化为英寸。
持久化保存返回的 jobId 并与后续状态响应进行比较。
将带有 failedCount > 0 的 completed 视为部分成功。
对商品列表进行分页，而非请求无限制的目录。
删除操作时，提供 productId 或 sku 中恰好一个。
实现带指数退避和随机抖动的有界重试。

关于凭据、商家接入值、商品类型映射或持续性集成问题，请联系您的 Ideal House 集成代表。