Erreurs

HIOBuy utilise deux formes d’erreur : les erreurs de protocole (HTTP non-2xx avec un objet error) et les résultats métier (HTTP 200 avec success: false sur certaines routes de commande).

Erreurs de protocole (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"
  }
}

Champ	Description
`error.code`	Énumération lisible par machine — à utiliser pour la logique de branchement
`error.message`	Explication lisible par un humain (anglais)
`error.request_id`	Identique à l’en-tête de réponse `x-request-id`
`error.category`	Groupe large : `AUTH_ERROR`, `RATE_LIMIT_ERROR`, `VALIDATION_ERROR`, `CHANNEL_ERROR`, `INTERNAL_ERROR`
`error.upstream`	Résumé optionnel de l’erreur fournisseur sur `CHANNEL_UPSTREAM_ERROR` (sanitisé)

Référence des codes d’erreur {#error-codes}

Le catalogue canonique lisible par machine est data/errors.catalog.json. Résumé :

Code	HTTP	Catégorie	Quand
`INVALID_API_KEY`	401	AUTH_ERROR	Jeton Bearer invalide ou manquant
`CHANNEL_NOT_AUTHORIZED`	401	AUTH_ERROR	Canal non autorisé pour cette app
`INSUFFICIENT_SCOPE`	403	AUTH_ERROR	Opération non autorisée pour cette clé/app
`FULFILLMENT_MODE_NOT_SUPPORTED`	403	AUTH_ERROR	`/v1/fulfillment/*` sur une app en fulfillment autonome
`VALIDATION_ERROR`	400	VALIDATION_ERROR	Champs de corps manquants/invalides, `currency` non pris en charge
`UNSUPPORTED_CHANNEL`	400	VALIDATION_ERROR	Valeur `channel` inconnue
`UNSUPPORTED_FIELD`	400	VALIDATION_ERROR	par ex. `currency` sur les routes produit
`NOT_FOUND`	404	VALIDATION_ERROR	Commande ou ressource inexistante
`RATE_LIMIT_EXCEEDED`	429	RATE_LIMIT_ERROR	Limite de débit par minute
`QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Quota quotidien de canal épuisé
`PLATFORM_QUOTA_EXCEEDED`	429	RATE_LIMIT_ERROR	Limite de capacité globale de la plateforme
`CHANNEL_CAPABILITY_NOT_SUPPORTED`	400	CHANNEL_ERROR	Opération indisponible sur ce canal
`CHANNEL_UPSTREAM_ERROR`	502	CHANNEL_ERROR	La marketplace a rejeté l’appel
`INTERNAL_ERROR`	500	INTERNAL_ERROR	Échec inattendu de la passerelle — réessayez avec backoff
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	Colis invalide ou pas encore reçu (fulfillment)
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	`shipping_channel_code` invalide
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	Solde du wallet fulfillment insuffisant pour payer

Échecs métier (HTTP 200) {#business-failures}

La prévisualisation/création/le paiement d’approvisionnement peut retourner HTTP 200 avec success: false lorsque la marketplace refuse l’opération alors que la requête Gateway est valide.

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

Vérifiez success avant de considérer l’appel comme terminé
Inspectez unavailable_lines (prévisualisation) ou failed_offers (création)
Succès partiel : 1688 peut retourner success: true avec failed_offers non vide

Échecs upstream produit {#upstream-product-errors}

Un Taobao口令 invalide, un produit manquant ou des timeouts fournisseur sur les routes produit retournent généralement 502 avec CHANNEL_UPSTREAM_ERROR — pas une enveloppe produit vide.

Gestion recommandée {#handling}

Journalisez request_id sur tous les chemins d’erreur.
Réessayez 429 et 500 avec backoff exponentiel ; ne réessayez pas 400 / 401 sans corriger l’entrée.
Sur 502 CHANNEL_UPSTREAM_ERROR, affichez le message fournisseur aux opérations ; réessayez éventuellement une fois pour les interruptions transitoires.
Création de commande : utilisez external_order_id / outer_purchase_id Taobao pour l’idempotence — voir Commandes d’approvisionnement.