Ошибки

HIOBuy использует две формы ошибок: protocol errors (HTTP не-2xx с объектом error) и business outcomes (HTTP 200 с success: false на некоторых order routes).

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"
  }
}

Поле	Описание
`error.code`	Машиночитаемый enum — используйте для branching logic
`error.message`	Человекочитаемое объяснение (английский)
`error.request_id`	То же значение, что и response header `x-request-id`
`error.category`	Крупная группа: `AUTH_ERROR`, `RATE_LIMIT_ERROR`, `VALIDATION_ERROR`, `CHANNEL_ERROR`, `INTERNAL_ERROR`
`error.upstream`	Опциональная сводка vendor error при `CHANNEL_UPSTREAM_ERROR` (sanitized)

Справочник кодов ошибок {#error-codes}

Канонический машиночитаемый каталог: data/errors.catalog.json. Кратко:

Код	HTTP	Категория	Когда
`INVALID_API_KEY`	401	AUTH_ERROR	Неверный или отсутствующий Bearer token
`CHANNEL_NOT_AUTHORIZED`	401	AUTH_ERROR	Канал не авторизован для этого приложения
`INSUFFICIENT_SCOPE`	403	AUTH_ERROR	Операция не разрешена для этого ключа/приложения
`FULFILLMENT_MODE_NOT_SUPPORTED`	403	AUTH_ERROR	`/v1/fulfillment/*` на self-fulfillment app
`VALIDATION_ERROR`	400	VALIDATION_ERROR	Отсутствующие/неверные поля body, неподдерживаемый `currency`
`UNSUPPORTED_CHANNEL`	400	VALIDATION_ERROR	Неизвестное значение `channel`
`UNSUPPORTED_FIELD`	400	VALIDATION_ERROR	Например, `currency` на product routes
`NOT_FOUND`	404	VALIDATION_ERROR	Заказ или ресурс не существует
`RATE_LIMIT_EXCEEDED`	429	RATE_LIMIT_ERROR	Rate limit за минуту
`QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Дневная квота канала исчерпана
`PLATFORM_QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Platform-wide capacity limit
`CHANNEL_CAPABILITY_NOT_SUPPORTED`	400	CHANNEL_ERROR	Операция недоступна на этом канале
`CHANNEL_UPSTREAM_ERROR`	502	CHANNEL_ERROR	Маркетплейс отклонил вызов
`INTERNAL_ERROR`	500	INTERNAL_ERROR	Неожиданный сбой Gateway — повторите с backoff
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	Неверная или еще не поступившая inbound parcel (fulfillment)
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	Некорректный `shipping_channel_code`
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	Недостаточно средств в fulfillment wallet для pay

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

Procurement preview/create/pay может вернуть HTTP 200 с success: false, когда маркетплейс отказывает в операции, но запрос Gateway был валидным.

{
  "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

Product upstream failures {#upstream-product-errors}

Неверный Taobao口令, отсутствующий товар или vendor timeouts на product routes обычно возвращают 502 с CHANNEL_UPSTREAM_ERROR, а не пустую оболочку товара.

Ошибки

Protocol errors (HTTP 4xx / 5xx) {#protocol-errors}

Справочник кодов ошибок {#error-codes}

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

Product upstream failures {#upstream-product-errors}

Рекомендуемая обработка {#handling}