Copy page

الأخطاء

تستخدم أخطاء التطبيق غلافًا موحدًا يحتوي على رسالة مقروءة وكود ثابت وفئة. وتضيف أخطاء التحقق تفاصيل على مستوى الحقول، وتُعيد الأخطاء غير المعروفة معرّف طلب للدعم.

Code
{
  "error": "Order not found",
  "code": "ORDER_NOT_FOUND",
  "category": "BUSINESS_LOGIC"
}

الغلاف

يُحذف context عندما لا يوجد ما يُضاف. لا تعتمد على تحليل رسالة error في منطقك؛ استخدم code.

الفئات

أخطاء التحقق

تُرجع إخفاقات التحقق في Zod الكود VALIDATION_FAILED مع عنصر لكل حقل:

Code
{
  "error": "Validation failed",
  "code": "VALIDATION_FAILED",
  "category": "VALIDATION",
  "context": {
    "fields": [
      {
        "path": "items.0.quantity",
        "message": "Expected number, received string",
        "code": "invalid_type"
      }
    ]
  }
}

path مفصول بنقاط ويمكن أن يشير داخل كائنات ومصفوفات متداخلة. وcode يأتي من Zod ويفيد في معالجة النماذج عمومًا؛ أما message فهو الشرح الموجّه للمطوّر.

الأخطاء غير المتوقعة

لا تكشف الأخطاء غير المعروفة الرسالة الأصلية أبدًا، لأنها قد تحتوي على SQL أو أسماء جداول أو مسارات ملفات أو أسرار. وتحمل الاستجابة بدلًا من ذلك معرّف طلب:

Code
{
  "error": "An unexpected error occurred",
  "code": "INTERNAL_SERVER_ERROR",
  "category": "SYSTEM",
  "context": {
    "requestId": "3f1c0a9e-6a1b-4a27-8f3e-0d1f2a7c9b11"
  }
}

يُسجَّل الخطأ الكامل على الخادم تحت معرّف الطلب نفسه. أرفقه عند الإبلاغ عن مشكلة.

استجابات خارج الغلاف

بعض الحمايات تجيب قبل تشغيل معالج أخطاء التطبيق وتستخدم جسمًا أصغر:

• إخفاقات نطاق RBAC تُرجع 403 مع { "error": "Insufficient permissions", "required": "orders:read" }.
• إخفاقات مفتاح المتجر تُرجع 401 مع { "error": "Missing store API key" } أو { "error": "Invalid store API key" }.

اعتبر أي جسم بلا code رفضًا على مستوى النقل، لا نتيجة على مستوى منطق العمل.

أكواد الحالة

إرشادات إعادة المحاولة

• لا تُعد المحاولة مع 400 أو 401 أو 403 أو 404 أو 422 بالطلب نفسه. غيّر الطلب أو بيانات الاعتماد أولًا.
• أعد المحاولة مع 500 بتراجع أُسّي مع عشوائية. واحتفظ بمعرّف الطلب من الاستجابة.
• الإنشاءات ليست متكررة بأمان افتراضيًا. إعادة محاولة الإنشاء قد تنشئ موردًا ثانيًا. قبل إعادة المحاولة، اقرأ المورد مرة أخرى عبر مفتاح طبيعي مثل رقم طلب أو handle أو رقم هاتف.
• Webhooks شركات التوصيل متكررة بأمان عند الاستلام. تزيل صندوق الوارد التكرار بحسب معرّف الحدث من المزوّد، لذا لا تعالج إعادة محاولة شركة التوصيل الحدث نفسه مرتين.

العثور على كود

يعرض مرجع API غلاف ErrorResponse الذي تستخدمه كل عملية. الأكواد معرّفات ثابتة مجمّعة حسب المجال: التحقق والمصادقة والطلبات والمنتجات والتوصيل والمراجعات وصفحات الهبوط وإدارة MCP وأخطاء النظام.