Lỗi

HIOBuy dùng hai dạng lỗi: protocol errors (HTTP không phải 2xx với object error) và business outcomes (HTTP 200 với success: false trên một số route đơn hàng).

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

Field	Mô tả
`error.code`	Enum cho máy đọc — dùng cho logic rẽ nhánh
`error.message`	Giải thích cho người đọc (tiếng Anh)
`error.request_id`	Giống header response `x-request-id`
`error.category`	Nhóm tổng quát: `AUTH_ERROR`, `RATE_LIMIT_ERROR`, `VALIDATION_ERROR`, `CHANNEL_ERROR`, `INTERNAL_ERROR`
`error.upstream`	Tóm tắt lỗi vendor tùy chọn trên `CHANNEL_UPSTREAM_ERROR` (đã sanitize)

Tham chiếu mã lỗi {#error-codes}

Catalog chính thức cho máy đọc là data/errors.catalog.json. Tóm tắt:

Code	HTTP	Category	Khi nào
`INVALID_API_KEY`	401	AUTH_ERROR	Bearer token không hợp lệ hoặc bị thiếu
`CHANNEL_NOT_AUTHORIZED`	401	AUTH_ERROR	Kênh chưa được ủy quyền cho app này
`INSUFFICIENT_SCOPE`	403	AUTH_ERROR	Key/app không được phép thực hiện thao tác
`FULFILLMENT_MODE_NOT_SUPPORTED`	403	AUTH_ERROR	`/v1/fulfillment/*` trên app self-fulfillment
`VALIDATION_ERROR`	400	VALIDATION_ERROR	Field body bị thiếu/không hợp lệ, `currency` không được hỗ trợ
`UNSUPPORTED_CHANNEL`	400	VALIDATION_ERROR	Giá trị `channel` không xác định
`UNSUPPORTED_FIELD`	400	VALIDATION_ERROR	ví dụ `currency` trên product routes
`NOT_FOUND`	404	VALIDATION_ERROR	Đơn hàng hoặc tài nguyên không tồn tại
`RATE_LIMIT_EXCEEDED`	429	RATE_LIMIT_ERROR	Rate limit theo phút
`QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Hết quota kênh hằng ngày
`PLATFORM_QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Giới hạn năng lực toàn nền tảng
`CHANNEL_CAPABILITY_NOT_SUPPORTED`	400	CHANNEL_ERROR	Thao tác không khả dụng trên kênh này
`CHANNEL_UPSTREAM_ERROR`	502	CHANNEL_ERROR	Marketplace từ chối cuộc gọi
`INTERNAL_ERROR`	500	INTERNAL_ERROR	Gateway lỗi ngoài dự kiến — retry với backoff
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	Kiện hàng không hợp lệ hoặc chưa nhập kho (fulfillment)
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	`shipping_channel_code` sai
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	Ví fulfillment không đủ để thanh toán

Lỗi nghiệp vụ (HTTP 200) {#business-failures}

Procurement preview/create/pay có thể trả về HTTP 200 với success: false khi marketplace từ chối thao tác nhưng request Gateway hợp lệ.

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

Kiểm tra success trước khi xem cuộc gọi là đã hoàn tất
Xem unavailable_lines (preview) hoặc failed_offers (create)
Thành công một phần: 1688 có thể trả success: true với failed_offers không rỗng

Lỗi upstream sản phẩm {#upstream-product-errors}

Taobao口令 không hợp lệ, sản phẩm bị thiếu hoặc vendor timeout trên product routes thường trả về 502 với CHANNEL_UPSTREAM_ERROR — không phải một product shell rỗng.

Cách xử lý khuyến nghị {#handling}

Ghi log request_id trên mọi nhánh lỗi.
Retry 429 và 500 với exponential backoff; không retry 400 / 401 khi chưa sửa input.
Với 502 CHANNEL_UPSTREAM_ERROR, hiển thị message vendor cho ops; có thể retry một lần cho sự cố tạm thời.
Order create: dùng external_order_id / Taobao outer_purchase_id để idempotency — xem Procurement orders.