Errors

HIOBuy uses two error shapes: protocol errors (non-2xx HTTP with an error object) and business outcomes (HTTP 200 with success: false on some order routes).

Protocol errors (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."
        }
      ]
    }
  }
}

Field-level details.fields[].code values: REQUIRED | INVALID_VALUE | INVALID_FORMAT | OUT_OF_RANGE.

HTTP status principles

Error code reference {#error-codes}

The canonical machine-readable catalog is data/errors.catalog.json. Summary:

Business failures (HTTP 200) {#business-failures}

Procurement preview/create/pay may return HTTP 200 with success: false when the marketplace refuses the operation but the Gateway request was valid.

{
  "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_..."
}

• Check success before treating the call as completed
• Inspect unavailable_lines (preview) or failed_offers (create)
• Partial success: 1688 may return success: true with non-empty failed_offers

Product upstream failures {#upstream-product-errors}

Invalid Taobao口令, missing product, or vendor timeouts on product routes typically return 502 with CHANNEL_UPSTREAM_ERROR — not an empty product shell.

Recommended handling {#handling}

1. Log request_id on every error path.
2. Retry 429 and 500 with exponential backoff; do not retry 400 / 401 without fixing input.
3. On 502 CHANNEL_UPSTREAM_ERROR, surface vendor message to ops; optionally retry once for transient outages.
4. Order create: use external_order_id / Taobao outer_purchase_id for idempotency — see Procurement orders.