شخّص بالحالة والرمز الثابت
احفظ X-Request-Id ومعرّف العملية والحالة. لا تسجّل مفتاح API أو عنوان URL للمستلم أو بيانات الاتصال أو صورة الدليل أو جسم خطاف الويب الخام. تعيد بعض نقاط النهاية code منظّمًا، وتعيد أخرى أخطاء تحقّق أو استجابة 401/403/404 فارغة. لا تفترض أن لكل خطأ بنية JSON نفسها، ولا تبنِ التفرّعات على نص الرسالة المترجم.
| الرمز أو الحالة | السبب المحتمل | إعادة المحاولة والإجراء التصحيحي |
|---|---|---|
| 401 | بيانات اعتماد مفقودة أو غير سليمة التنسيق أو ملغاة أو منتهية | صحّح بيانات الاعتماد؛ لا تُعد الطلب دون تعديل |
| 403 | نطاق أو إذن حساب مفقود | تحقّق من نطاق العملية والبيئة؛ حدّث بيانات الاعتماد بعد تغيير الإعدادات |
| 404 | معرّف أو بيئة خاطئة أو صلاحية وصول منتهية أو غير صالحة | تحقّق من القراءة المرجعية المصادَق عليها والبيئة |
| 429 | حد المعدّل أو الحصة | التزم بـ Retry-After؛ طبّق تراجعًا أُسّيًا مع تفاوت عشوائي |
| 5xx / إخفاق النقل | إخفاق مؤقت في الخدمة أو الشبكة | أعد استخدام المعرّفات والحمولة نفسها، وحدّد عدد المحاولات، وافحص الحالة المرجعية بعد نتيجة غير مؤكّدة |
returns_paused | عمليات كتابة المرتجعات غير متاحة مؤقتًا | أعد المحاولة لاحقًا بالمعرّفات نفسها؛ تبقى القراءة متاحة |
idempotency_key_invalid | مفتاح الإنشاء مفقود أو طويل جدًا | قدّم مفتاحًا ثابتًا غير فارغ لا يتجاوز 160 حرفًا |
idempotency_conflict | إعادة استخدام مفتاح لعملية مختلفة | استعد الطلب الأصلي أو استخدم مفتاحًا لعملية جديدة فعلًا |
event_id_invalid | UUID مفقود أو فارغ | ولّد UUID واحدًا لكل حدث واحفظه |
occurred_at_invalid | وقت الحدث في المستقبل | صحّح الساعة أو الطابع الزمني؛ احفظ وقت الحدوث الفعلي |
return_not_eligible | حالة الشحنة الصادرة لا تسمح بنوع الإرجاع | يحتاج إرجاع العميل إلى Delivered؛ ويحتاج RTS بعد فشل التوصيل إلى DeliveryAttempted |
return_state_conflict | انتقال غير صالح أو تبعية دليل أو حدث متعارض | اقرأ الحالة المرجعية ومتطلبات الدليل؛ صحّح قبل ال إعادة |
return_conflict | قيد تزامن مرتجع أو معرّف | اقرأ المرتجع الحالي؛ لا تنشئ عملًا ماديًا مكررًا |
return_origin_invalid, return_destination_invalid | لقطة مفقودة أو غير صالحة | قدّم حقول عنوان مؤكّد وإحداثيات صالحة |
return_event_invalid | مدخل حدث غير صالح | صحّح المدخل وفق مرجع API |
return_pickup_confirmation_not_allowed | الوصول للاستلام غير مسموح في الحالة الحالية | افحص حالة التفويض والتسليم قبل إصدار رابط جديد |
return_proof_asset_missing | المرجع لا يشير إلى أصل مرتجع مرفوع | ارفع PNG أولًا مع مطابقة المرتجع والدليل والنوع؛ واستخدم المرجع المُعاد |
return_proof_invalid, proof_image_invalid | صورة أو حقول دليل غير صالحة | صحّح الطريقة والغرض والأبعاد والحجم والطابع الزمني |
return_proof_conflict | إعادة استخدام UUID للدليل بمحتوى مختلف | أعد الدليل نفسه؛ لا تستبدل الأدلة غير القابلة للتعديل |
return_destination_required | سياسة RTS تحتاج إلى وجهة | قدّم وجهة المرسل أو التاجر المتفق عليها |
مشكلات التكامل الشائعة
المفتاح المنسوخ يبدأ بـ [object Object]: أعد نسخ بيانات الاعتماد من اللوحة. لا يحتوي المفتاح على أيقونة أو ترميز أو نص عرض لاحق. اضبط القيمة الخام الكاملة.
حالة التوصيل لم تتقدّم بعد إرسال الدليل: افحص مزامنة الدليل. النطاق delivery:proof منفصل عن delivery:events. يمنع فشل الدليل حدث الإكمال المعتمد عليه. أصلح الإعدادات وأعد العملية الأصلية بالمعرّفات نفسها.
بريدي الإلكتروني مطابق لكن رابط المستلم لا يعمل: تأكّد من صحة بيانات اتصال الشحنة المرجعية ومن التحقّق من جهة الاتصال في الحساب. لا تغيّر بيانات اتصال تُستخدم لتأكيد العنوان فقط ملكية الشحنة. يثبت التتبّع العام التقدّم لا تفويض المستلم.
لا يتوفر خيار إرجاع: يجب ربط الشحنة وأن تكون حالتها المرجعية Delivered قبل بدء إرجاع العميل.
رُفض عنوان URL لدليل الإرجاع: ارفع PNG حقيقيًا عبر API أصول المرتجعات. لا يفي توقيع نصي أو عنوان URL عشوائي للتاجر بهذا العقد.
فشل توقيع خطاف الويب: احتفظ بالبايتات الخام وتحقّق من سر الاشتراك الصحيح وحداثة الطابع الزمني وتجنّب إعادة تسلسل JSON. راجع وصفات خطافات الويب.