الأخطاء

هناك شكلان للخطأ، وواحد منهما فقط يحمل code.

أخطاء المجال تحمل رمزًا

{
  "success": false,
  "statusCode": 409,
  "code": "VIEWING_SLOT_TAKEN",
  "message": "That time has just been booked — please pick another.",
  "details": { "propertyId": "…", "date": "2026-09-20", "slot": "11:00" },
  "path": "/api/public/viewing-requests",
  "method": "POST",
  "timestamp": "2026-09-14T09:30:27.019Z"
}

code في المستوى الأعلى لا داخل حقل آخر. وdetails اختياري ويختلف مع كل رمز. تفرّع على code، ولا تتفرّع أبدًا على message المكتوبة للبشر والمترجمة مع الوقت.

أخطاء التحقّق لا تحمل رمزًا

الجسم أو الاستعلام الذي ترفضه الواجهة هو 400 فيه مصفوفة نصوص في message وبلا code إطلاقًا:

{
  "success": false,
  "statusCode": 400,
  "message": ["property type should not exist"],
  "error": "Bad Request",
  "path": "/api/public/properties",
  "method": "GET"
}

ودالّة واحدة في طبقة الاتصال تغطّي الحالتين:

function apiError(body: any) {
  if (body?.code) return { code: body.code as string, message: body.message };
  const message = Array.isArray(body?.message) ? body.message.join(', ') : body?.message;
  return { code: 'VALIDATION_FAILED', message };
}

وبغير هذا الفحص سيعرض نصف نماذجك [object Object].

تعريف الموقع

انظر تعريف موقعك.

مفاتيح الواجهة

وما دام الطرح في وضع المراقبة فهذه تُسجَّل ولا تُعاد. انظر المفاتيح وCORS.

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

انظر الحماية من الروبوتات.

طلبات المعاينة

الأربعة تعني للزائر الشيء نفسه — «هذا الوقت لم يعد متاحًا، اختر غيره» — فاجعلها رسالة واحدة، وأبطِل ما خزّنته من GET /public/properties/{id}/viewing-slots، وامسح الوقت المختار. تُعلّم نقطة المواعيد الأوقات المحجوزة بـ available: false أصلًا؛ والـ 409 لا يغلق إلا السباق بين زائرَين.

حسابات الزوّار

رموز VISITOR_TOKEN_REQUIRED وVISITOR_TOKEN_INVALID وVISITOR_EMAIL_TAKEN وVISITOR_CREDENTIALS_INVALID وVISITOR_EMAIL_NOT_VERIFIED وOTP_INVALID وOTP_EXPIRED وOTP_LOCKED وRESET_TOKEN_INVALID وأخواتها مشروحة مع طريقة معالجتها في حسابات الزوّار.

«غير موجود» والسقوف

أخطاء 404 من الكتالوج موحّدة الشكل: PROPERTY_NOT_FOUND وPROJECT_NOT_FOUND وLOCATION_NOT_FOUND وVIEWING_REQUEST_NOT_FOUND وVISITOR_SAVED_SEARCH_NOT_FOUND وOWNER_SUBMISSION_NOT_FOUND، ولكل منها details: { id }. أما FAVORITES_CAP (409) فهو المفضّل الحادي عشر من نوعه.

حدود المعدّل

الرفض هو HTTP 429 بلا code في الجسم — الحالة نفسها هي الإشارة. توقّف، وتراجع، وأخبر الزائر أن يحاول بعد قليل؛ ولا تُعِد المحاولة في حلقة ضيّقة، ولا تُعِد محاولة كتابة تلقائيًّا أبدًا.

أخطاء لن تلقاها إلا داخل النظام

هذه من واجهة الموظّفين لا من /api/public/*. وهي هنا لأنها ما تراه أثناء إعداد الموقع.