الأخطاء

تفرّع على statusMessage وstatusCode في HTTP، لا على error.message المترجم.

الغلاف

{
  "success": false,
  "statusCode": 400,
  "statusMessage": "VALIDATION_ERROR",
  "results": null,
  "error": {
    "message": "خطأ في التحقق",
    "data": []
  }
}

رسائل الحالة

statusMessage	HTTP	متى
SUCCESS	200	نجاح عام
CREATED	200	أُنشئ المورد
UPDATED	200	طُبّق التعديل (إجراءات التجهيز)
DELETED	200	حُذف
DATA_LOADED	200	قائمة / قراءة
VALIDATION_ERROR	400	مخطط أو قاعدة عمل (بما فيها وضع الصيانة)
SLUG_TAKEN	400	تعارض اختصار فريد
OUT_OF_STOCK	400	السلة / الإنشاء
CART_EMPTY	400	الإنشاء أو إجراء السلة
INVALID_CREDENTIALS	401	كلمة مرور موظف أو OTP خاطئ
INVALID_TOKEN	401	رمز سيئ
TOKEN_EXPIRED	401	انتهت صلاحية OTP / الرمز
AUTHENTICATION_REQUIRED	401	غياب JWT العميل أو الموظف
UNAUTHENTICATED	401	رُفض JWT
FORBIDDEN	403	مصادق لكن غير مسموح
ACCESS_DENIED	403	صلاحية ناقصة (مثل orders:update)
RESOURCE_NOT_FOUND	404	معرّف مجهول
RESOURCE_EXISTS	409	تكرار
RATE_LIMITED	429	حد Redis
TOO_MANY_ATTEMPTS	429	تقييد OTP / الدخول
INTERNAL_ERROR	500	غير متوقع
SERVICE_UNAVAILABLE	503	اعتماد متوقف

إخفاقات المصادقة

الموقف	الرمز المعتاد
مسار عميل بلا Bearer	AUTHENTICATION_REQUIRED / UNAUTHENTICATED
مسار موظف بلا Bearer	نفسه
POST ملتقط/سائق بلا orders:update	ACCESS_DENIED
واجهة دور خاطئ	ما يزال 200 على /auth/me — اخفِ الشاشات باستخدام roleKey

المتجر مغلق

تعديلات /v1/cart و/v1/orders (POST) و/v1/account/wishlist أثناء وضع الصيانة ترجع VALIDATION_ERROR مع رسالة إغلاق مترجمة.

قائمة فحص العميل

1. إن كان success === false اعرض error.message للمستخدم.
2. إن كان statusCode === 401 في تطبيق العميل استدعِ POST /v1/auth/refresh مرة وأعد المحاولة. إن فشل التحديث أرسله إلى OTP.
3. إن كان statusCode === 401 في الملتقط/السائق حدّث JWT الموظف مرة؛ إن فشل أرسله إلى دخول الموظف.
4. أعد محاولة 429 بتراجع.
5. بعد كل POST تجهيز أعد تحميل الطلب؛ لا تفترض الحالة المحلية.
6. POST /v1/assistant/messages وGET /v1/notifications/sse هما SSE — حلّل أسطر event: / data: وليس غلاف JSON.