错误码

HIOBuy 有两类错误形态：协议错误（非 2xx，含 error 对象）与 业务失败（部分订单路由 HTTP 200 且 success: false）。

协议错误（HTTP 4xx / 5xx） {#protocol-errors}

{
  "error": {
    "code": "INBOUND_VALIDATION_FAILED",
    "message": "Some inbound information is missing or invalid.",
    "request_id": "req_abc123",
    "category": "VALIDATION_ERROR",
    "field": "tracking_number",
    "details": {
      "fields": [
        {
          "field": "items[0].name",
          "code": "REQUIRED",
          "message": "Product name is required."
        }
      ]
    }
  }
}

字段级 details.fields[].code：REQUIRED | INVALID_VALUE | INVALID_FORMAT | OUT_OF_RANGE。

HTTP 状态原则

错误码参考 {#error-codes}

机器可读权威目录见 data/errors.catalog.json。摘要：

业务失败（HTTP 200） {#business-failures}

采购 preview/create/pay 在市场拒绝但 Gateway 请求合法时，可能返回 HTTP 200 且 success: false。

{
  "channel": "1688",
  "success": false,
  "code": "ORDER_CREATE_FAILED",
  "message": "One or more lines could not be purchased.",
  "failed_offers": [
    {
      "offer_id": "...",
      "spec_id": "...",
      "error_code": "STOCK_NOT_ENOUGH",
      "error_message": "Insufficient stock"
    }
  ],
  "request_id": "req_..."
}

• 先检查 success
• 查看 unavailable_lines（preview）或 failed_offers（create）
• 部分成功：1688 可能 success: true 且 failed_offers 非空

商品上游失败 {#upstream-product-errors}

无效淘宝口令、商品不存在或厂商超时等，商品路由通常返回 502 CHANNEL_UPSTREAM_ERROR，而不是空商品壳。

建议处理 {#handling}

1. 每条错误路径记录 request_id。
2. 对 429 / 500 指数退避重试；未修正输入前不要重试 400 / 401。
3. 对 502 CHANNEL_UPSTREAM_ERROR，向运维展示厂商信息；瞬时故障可再试一次。
4. 创单使用 external_order_id / 淘宝 outer_purchase_id 做幂等 — 见 采购订单。