Fehler

HIOBuy verwendet zwei Fehlerformen: Protokollfehler (Nicht-2xx-HTTP mit einem error-Objekt) und geschäftliche Ergebnisse (HTTP 200 mit success: false auf einigen Bestell-Routen).

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

Feld	Beschreibung
`error.code`	Maschinenlesbares Enum - für Branching-Logik verwenden
`error.message`	Menschenlesbare Erklärung (Englisch)
`error.request_id`	Identisch mit dem Antwort-Header `x-request-id`
`error.category`	Grobe Gruppierung: `AUTH_ERROR`, `RATE_LIMIT_ERROR`, `VALIDATION_ERROR`, `CHANNEL_ERROR`, `INTERNAL_ERROR`
`error.upstream`	Optionale Vendor-Fehlerzusammenfassung bei `CHANNEL_UPSTREAM_ERROR` (bereinigt)

Fehlercode-Referenz {#error-codes}

Der kanonische maschinenlesbare Katalog ist data/errors.catalog.json. Zusammenfassung:

Code	HTTP	Kategorie	Wann
`INVALID_API_KEY`	401	AUTH_ERROR	Ungültiges oder fehlendes Bearer-Token
`CHANNEL_NOT_AUTHORIZED`	401	AUTH_ERROR	Channel für diese App nicht autorisiert
`INSUFFICIENT_SCOPE`	403	AUTH_ERROR	Vorgang für diesen Schlüssel/diese App nicht erlaubt
`FULFILLMENT_MODE_NOT_SUPPORTED`	403	AUTH_ERROR	`/v1/fulfillment/*` auf Self-Fulfillment-App
`VALIDATION_ERROR`	400	VALIDATION_ERROR	Fehlende/ungültige Body-Felder, nicht unterstütztes `currency`
`UNSUPPORTED_CHANNEL`	400	VALIDATION_ERROR	Unbekannter `channel`-Wert
`UNSUPPORTED_FIELD`	400	VALIDATION_ERROR	z. B. `currency` auf Produkt-Routen
`NOT_FOUND`	404	VALIDATION_ERROR	Bestellung oder Ressource existiert nicht
`RATE_LIMIT_EXCEEDED`	429	RATE_LIMIT_ERROR	Rate Limit pro Minute
`QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Tägliches Channel-Kontingent erschöpft
`PLATFORM_QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Plattformweites Kapazitätslimit
`CHANNEL_CAPABILITY_NOT_SUPPORTED`	400	CHANNEL_ERROR	Vorgang auf diesem Channel nicht verfügbar
`CHANNEL_UPSTREAM_ERROR`	502	CHANNEL_ERROR	Marketplace hat den Aufruf abgelehnt
`INTERNAL_ERROR`	500	INTERNAL_ERROR	Unerwarteter Gateway-Fehler - mit Backoff erneut versuchen
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	Ungültiges oder noch nicht eingegangenes Paket (Fulfillment)
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	Ungültiger `shipping_channel_code`
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	Fulfillment-Wallet-Guthaben zu niedrig für Zahlung

Geschäftliche Fehlschläge (HTTP 200) {#business-failures}

Beschaffungs-Preview/Create/Pay kann HTTP 200 mit success: false zurückgeben, wenn der Marketplace den Vorgang ablehnt, die Gateway-Anfrage aber gültig war.

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

Prüfen Sie success, bevor Sie den Aufruf als abgeschlossen behandeln
Untersuchen Sie unavailable_lines (Preview) oder failed_offers (Create)
Teilerfolg: 1688 kann success: true mit nicht leerem failed_offers zurückgeben

Produkt-Upstream-Fehler {#upstream-product-errors}

Ungültiges Taobao口令, fehlendes Produkt oder Vendor-Timeouts auf Produkt-Routen geben typischerweise 502 mit CHANNEL_UPSTREAM_ERROR zurück - keine leere Produkthülle.

Empfohlene Behandlung {#handling}

request_id auf jedem Fehlerpfad loggen.
429 und 500 mit exponentiellem Backoff erneut versuchen; 400 / 401 nicht ohne Korrektur der Eingabe erneut versuchen.
Bei 502 CHANNEL_UPSTREAM_ERROR Vendor-Nachricht an Operations anzeigen; optional einmal bei transienten Ausfällen erneut versuchen.
Order Create: external_order_id / Taobao outer_purchase_id für Idempotenz verwenden - siehe Beschaffungsbestellungen.