Errores

HIOBuy usa dos formas de error: errores de protocolo (HTTP no 2xx con un objeto error) y resultados de negocio (HTTP 200 con success: false en algunas rutas de pedidos).

Errores de protocolo (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"
  }
}

Campo	Descripción
`error.code`	Enumeración legible por máquina; úsala para lógica de ramificación
`error.message`	Explicación legible por humanos (inglés)
`error.request_id`	Igual que el encabezado de respuesta `x-request-id`
`error.category`	Agrupación general: `AUTH_ERROR`, `RATE_LIMIT_ERROR`, `VALIDATION_ERROR`, `CHANNEL_ERROR`, `INTERNAL_ERROR`
`error.upstream`	Resumen opcional del error del proveedor en `CHANNEL_UPSTREAM_ERROR` (saneado)

Referencia de códigos de error {#error-codes}

El catálogo canónico legible por máquina es data/errors.catalog.json. Resumen:

Código	HTTP	Categoría	Cuándo
`INVALID_API_KEY`	401	AUTH_ERROR	Token Bearer inválido o ausente
`CHANNEL_NOT_AUTHORIZED`	401	AUTH_ERROR	Canal no autorizado para esta app
`INSUFFICIENT_SCOPE`	403	AUTH_ERROR	Operación no permitida para esta clave/app
`FULFILLMENT_MODE_NOT_SUPPORTED`	403	AUTH_ERROR	`/v1/fulfillment/*` en una app con fulfillment propio
`VALIDATION_ERROR`	400	VALIDATION_ERROR	Campos del cuerpo ausentes/invalidos, `currency` no compatible
`UNSUPPORTED_CHANNEL`	400	VALIDATION_ERROR	Valor `channel` desconocido
`UNSUPPORTED_FIELD`	400	VALIDATION_ERROR	Por ejemplo, `currency` en rutas de producto
`NOT_FOUND`	404	VALIDATION_ERROR	El pedido o recurso no existe
`RATE_LIMIT_EXCEEDED`	429	RATE_LIMIT_ERROR	Límite de tasa por minuto
`QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Cuota diaria de canal agotada
`PLATFORM_QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Límite de capacidad de toda la plataforma
`CHANNEL_CAPABILITY_NOT_SUPPORTED`	400	CHANNEL_ERROR	Operación no disponible en este canal
`CHANNEL_UPSTREAM_ERROR`	502	CHANNEL_ERROR	El marketplace rechazó la llamada
`INTERNAL_ERROR`	500	INTERNAL_ERROR	Fallo inesperado de Gateway; reintenta con backoff
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	Paquete inválido o aún no ingresado (fulfillment)
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	`shipping_channel_code` incorrecto
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	Saldo insuficiente en la billetera de fulfillment para pagar

Fallos de negocio (HTTP 200) {#business-failures}

Procurement preview/create/pay puede devolver HTTP 200 con success: false cuando el marketplace rechaza la operación pero la solicitud de Gateway era válida.

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

Comprueba success antes de tratar la llamada como completada
Inspecciona unavailable_lines (preview) o failed_offers (create)
Éxito parcial: 1688 puede devolver success: true con failed_offers no vacío

Fallos upstream de productos {#upstream-product-errors}

Taobao口令 inválido, producto inexistente o timeouts del proveedor en rutas de producto normalmente devuelven 502 con CHANNEL_UPSTREAM_ERROR, no una estructura de producto vacía.

Manejo recomendado {#handling}

Registra request_id en cada ruta de error.
Reintenta 429 y 500 con backoff exponencial; no reintentes 400 / 401 sin corregir la entrada.
En 502 CHANNEL_UPSTREAM_ERROR, muestra el mensaje del proveedor a operaciones; opcionalmente reintenta una vez si parece una interrupción transitoria.
Creación de pedidos: usa external_order_id / outer_purchase_id de Taobao para idempotencia; consulta Pedidos de compra.