エラー

HIOBuy は2種類のエラー形式を使用します。プロトコルエラー (非 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`	機械判読可能な enum。分岐ロジックに使用します
`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 です。概要:

コード	HTTP	分類	発生条件
`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}

調達の preview/create/pay は、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 (preview) または failed_offers (create) を確認してください
部分成功: 1688 は failed_offers が空でない状態でも success: true を返す場合があります

商品アップストリームの失敗 {#upstream-product-errors}

商品ルートでの無効な Taobao口令、存在しない商品、ベンダータイムアウトは通常、空の商品シェルではなく CHANNEL_UPSTREAM_ERROR 付きの 502 を返します。

推奨される処理 {#handling}

すべてのエラーパスで request_id をログに記録します。
429 と 500 は指数バックオフで再試行します。入力を修正せずに 400 / 401 を再試行しないでください。
502 CHANNEL_UPSTREAM_ERROR では、ベンダーメッセージを運用担当に表示します。一時的な障害であれば任意で1回だけ再試行します。
注文作成では冪等性のために external_order_id / Taobao outer_purchase_id を使用します。Procurement orders を参照してください。