错误

HIOBuy 使用两种错误形态：协议错误（非 2xx HTTP，带 error 对象）与业务结果（部分订单路由在 HTTP 200 下返回 success: false）。

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

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "product_id, url, mi_id, or tao_password is required.",
    "request_id": "req_abc123",
    "category": "VALIDATION_ERROR"
  }
}

字段	说明
`error.code`	机器可读枚举——用于分支逻辑
`error.message`	人类可读说明（英文）
`error.request_id`	与 `x-request-id` 响应头相同
`error.category`	粗粒度分组：`AUTH_ERROR`、`RATE_LIMIT_ERROR`、`VALIDATION_ERROR`、`CHANNEL_ERROR`、`INTERNAL_ERROR`
`error.upstream`	`CHANNEL_UPSTREAM_ERROR` 时可选的上游错误摘要（已脱敏）

错误码参考 {#error-codes}

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

Code	HTTP	Category	触发场景
`INVALID_API_KEY`	401	AUTH_ERROR	Bearer 令牌无效或缺失
`CHANNEL_NOT_AUTHORIZED`	401	AUTH_ERROR	该应用未授权此渠道
`INSUFFICIENT_SCOPE`	403	AUTH_ERROR	该密钥/应用无权执行此操作
`FULFILLMENT_MODE_NOT_SUPPORTED`	403	AUTH_ERROR	自履约应用调用 `/v1/fulfillment/*`
`VALIDATION_ERROR`	400	VALIDATION_ERROR	请求体字段缺失/无效，或不支持 `currency`
`UNSUPPORTED_CHANNEL`	400	VALIDATION_ERROR	未知 `channel` 值
`UNSUPPORTED_FIELD`	400	VALIDATION_ERROR	例如商品路由上传 `currency`
`NOT_FOUND`	404	VALIDATION_ERROR	订单或资源不存在
`RATE_LIMIT_EXCEEDED`	429	RATE_LIMIT_ERROR	每分钟速率超限
`QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	渠道日配额耗尽
`PLATFORM_QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	平台级容量上限
`CHANNEL_CAPABILITY_NOT_SUPPORTED`	400	CHANNEL_ERROR	该渠道不支持此操作
`CHANNEL_UPSTREAM_ERROR`	502	CHANNEL_ERROR	卖场拒绝了调用
`INTERNAL_ERROR`	500	INTERNAL_ERROR	Gateway 意外故障——请退避重试
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	包裹无效或尚未入库（履约）
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	`shipping_channel_code` 无效
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	履约钱包余额不足以支付

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

当卖场拒绝操作但 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（预览）或 failed_offers（创建）
部分成功：1688 可能返回 success: true 且 failed_offers 非空

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

商品路由上无效的淘宝口令、商品不存在或上游超时，通常返回 502 且 CHANNEL_UPSTREAM_ERROR——而非空的商品壳体。

错误

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

错误码参考 {#error-codes}

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

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

推荐处理方式 {#handling}