الأخطاء

تستخدم HIOBuy شكلين للأخطاء: أخطاء البروتوكول (HTTP غير 2xx مع كائن 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. ملخص:

Code	HTTP	Category	متى يحدث
`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/*` على تطبيق self-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 — أعد المحاولة مع backoff
`PARCEL_NOT_FOUND`	404	VALIDATION_ERROR	طرد fulfillment غير صالح أو لم يصل بعد
`INVALID_SHIPPING_CHANNEL`	400	VALIDATION_ERROR	قيمة `shipping_channel_code` غير صحيحة
`INSUFFICIENT_BALANCE`	402	VALIDATION_ERROR	رصيد محفظة fulfillment غير كاف للدفع

فشل الأعمال (HTTP 200) {#business-failures}

قد تعيد 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 غير فارغة

فشل upstream للمنتجات {#upstream-product-errors}

عادة ما تعيد Taobao口令 غير الصالحة، أو المنتج المفقود، أو مهلات المزود في مسارات المنتجات 502 مع CHANNEL_UPSTREAM_ERROR — وليس غلاف منتج فارغا.

المعالجة الموصى بها {#handling}

سجل request_id في كل مسار خطأ.
أعد محاولة 429 و500 باستخدام exponential backoff؛ لا تعد محاولة 400 / 401 قبل إصلاح الإدخال.
عند 502 CHANNEL_UPSTREAM_ERROR، اعرض رسالة المزود لفريق التشغيل؛ ويمكنك اختياريا إعادة المحاولة مرة واحدة للأعطال العابرة.
إنشاء الطلب: استخدم external_order_id / Taobao outer_purchase_id لضمان idempotency — راجع طلبات الشراء.