الأخطاء ورموز الحالة في واجهات الـ API

الغرض#

تسرد هذه الصفحة رموز حالة HTTP وأكواد الأخطاء التي تعيدها فعلاً واجهة التاجر (/api/v1) وواجهة الشركة (/api/company/v1)، ومعنى كل منها وطريقة إصلاحه. ابنِ معالجة الأخطاء على error.code.

شكل الخطأ#

النجاح هو 200، أو 201 عند إنشاء مورد جديد، كطرد أو رابط ويب هوك. و200 مع "duplicate": true تعني أن reference موجود مسبقاً (واجهة التاجر). وكل خطأ يُرجعه الـ API نفسه يأتي بهذا الشكل:

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "...",
    "fields": { "customer_phone": ["..."] }
  }
}

• code كود قصير بصيغة snake_case، وعليه يعتمد برنامجك.
• message نص بلغة الطلب: العربية افتراضياً، والإنجليزية مع Accept-Language: en. وبعض الرسائل موجودة بالعربية فقط، فلا تبنِ المنطق على النص أبداً.
• يظهر fields في معظم أخطاء التحقق: أسماء الحقول مع رسائلها، ويكرّر message عادةً أول رسالة فيها (والاستثناء خطأ merchant_id في واجهة الشركة: يحمل fields.merchant_id الرسالة «تاجر غير موجود عند شركتك.» بينما يحمل message نص merchant_id الأطول الوارد في جدول التحقق). وبعض أخطاء واجهة الشركة (stage غير معروف، أو deliveryman_id ناقص أو لمندوب من شركة أخرى، أو action غير معروف) تحمل message فقط. وأسماء الحقول هي الأسماء الداخلية للمنصة (customer_name وcustomer_phone وcustomer_address وcustomer_city وlat وlong وshop_id بدل pickup_location_id).
• يظهر retry_after (بالثواني) مع rate_limited، وreference مع server_error، وresponse_status مع delivery_failed.

ترتيب الفحوصات#

يمرّ كل استدعاء بهذه الفحوصات ويتوقف عند أول فشل. وبعدها تطبّق النقطة قواعد التحقق وقواعد العمل الخاصة بها.

رموز الحالة وأكواد الأخطاء#

وهكذا يظهر الحقلان الإضافيان retry_after وreference:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "...",
    "retry_after": 42
  }
}

{
  "success": false,
  "error": {
    "code": "server_error",
    "message": "...",
    "reference": "E3FA91C"
  }
}

أخطاء التحقق (422)#

يربط fields كل حقل فاشل برسائله. وهذه الحقول التي ستصادفها أكثر من غيرها:

أخطاء خارج هذا الشكل#

تُنتَج بعض الأخطاء قبل أن يعمل كود الـ API، فلا تستخدم الغلاف:

• المسار غير الموجود (404) وطريقة HTTP الخاطئة (405) والحد العام للطلبات وحدود المسارات (429). مع Accept: application/json تحصل على جسم JSON فيه message؛ وبدونها تحصل على صفحة HTML.
• ومع ترويسة JSON تردّ هذه الحدود بـ {"message": "Too Many Attempts."} ومعه الترويسات Retry-After وX-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset. فقد يأتي 429 من ثلاثة مصادر: الحد العام (60 طلباً في الدقيقة لكل عنوان IP) وحدود المسارات (بلا error.code)، وحدّ الباقة (rate_limited داخل الغلاف).
• في حالات نادرة قد يقع خلل غير متوقع قبل معالجة الأخطاء الخاصة بالـ API، فيكون الرد {"success": false, "message": "..."} مع 500.

{ "message": "Too Many Attempts." }

التعامل مع الأخطاء في برنامجك#

1. افحص حالة HTTP أولاً

   4xx تعني أن طلبك يجب أن يتغيّر، عدا 429. و5xx تعني عادةً أن المشكلة من جهة المنصة، فأعد المحاولة لاحقاً. وهناك حالة لا تزول بإعادة المحاولة: في واجهة الشركة، تعيين مندوب لطرد لا تسمح حالته بالانتقال إلى «مع مندوب التوصيل»، كطرد بانتظار الاستلام أو ما زال في مرحلة الاستلام، يعطي 500 والكود server_error في كل مرة؛ فافحص status_code للطرد قبل استدعاء التعيين.

2. اعتمد على error.code

   استخدم error.code لتحديد ما يفعله برنامجك، وerror.fields لإبراز الحقول، وerror.message لعرضه على المستخدم فقط.

3. انتظر عند 429

   توقّف مدة error.retry_after ثانية، أو المدة الواردة في ترويسة Retry-After عندما يردّ الحد العام أو أحد حدود المسارات (بلا error.code)، ثم أعد المحاولة.

4. اجعل إعادة محاولة الإنشاء آمنة

   بعد انتهاء المهلة أو 500 عند إنشاء طرد، ابحث عن الطرد قبل إنشائه من جديد: بـ GET /parcels/{reference} في واجهة التاجر، وبـ GET /parcels?merchant_id=<id>&reference=<reference> في واجهة الشركة (فـ GET /parcels/{reference} وحده هناك يبحث في طرود كل تجّارك وقد يُرجع طرد تاجر آخر). وفي واجهة التاجر يُرجع إرسال reference نفسه الطرد الموجود مع "duplicate": true.

أخطاء شائعة#

• اعتبار 200 مع "duplicate": true طرداً جديداً. هو الطرد الذي أنشأته سابقاً.
• توقّع 409 عند تكرار reference في واجهة التاجر. ذلك في واجهة الشركة؛ أما واجهة التاجر فتُرجع الطرد القديم.
• إعادة محاولة 4xx دون تغيير. أصلح الطلب أولاً.
• تحليل error.message. يتغيّر مع اللغة، وبعض الرسائل بالعربية فقط.
• عدم إرسال Accept: application/json. عندها تصلك الأخطاء التي تقع قبل كود الـ API (انظر «أخطاء خارج هذا الشكل») صفحات HTML.
• تجاهل fields. فهو، عندما يوجد، يسمّي الحقل الذي فشل بالضبط.

الحدود والصلاحيات#

• plan_feature وrate_limited وapi_not_allowed تتوقف على باقتك ونوع حسابك، لا على جسم الطلب.
• تُستخدم اللغتان ar وen فقط في الرسائل.
• الأكواد المعلَّمة «التاجر» أو «الشركة» موجودة في تلك الواجهة وحدها.