رموز الخطأ

مرجع كامل لجميع رموز أخطاء API.

تنسيق استجابة الخطأ

عند حدوث خطأ، تُرجع API استجابة بالتنسيق التالي:

JSON
{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "وصف الخطأ القابل للقراءة",
        "details": {
            // معلومات إضافية (اختياري)
        }
    }
}

الحقول

الحقل النوع الوصف
code string رمز الخطأ الفريد (لبرمجة المنطق)
message string رسالة وصفية (يمكن عرضها للمستخدم)
details object تفاصيل إضافية (حقول غير صالحة، إلخ)

أخطاء المصادقة (401, 403)

الرمز HTTP الوصف
MISSING_API_KEY 401 لم يتم تضمين رأس X-API-Key
INVALID_API_KEY 401 مفتاح API غير صالح أو غير موجود
API_KEY_DISABLED 403 تم تعطيل مفتاح API
API_KEY_EXPIRED 403 انتهت صلاحية مفتاح API
ORIGIN_NOT_ALLOWED 403 النطاق الأصلي غير مصرح به
TENANT_INACTIVE 403 حساب النشاط التجاري غير نشط
MISSING_TOKEN 401 مطلوب رمز JWT ولكن لم يتم توفيره
INVALID_TOKEN 401 رمز JWT غير صالح أو مشوه
TOKEN_EXPIRED 401 انتهت صلاحية رمز JWT
INVALID_CREDENTIALS 401 البريد الإلكتروني أو كلمة المرور غير صحيحة (تسجيل الدخول)

أخطاء تحديد المعدل (429)

الرمز HTTP الوصف
RATE_LIMIT_EXCEEDED 429 طلبات كثيرة جداً، انتظر قبل إعادة المحاولة
LOGIN_ATTEMPTS_EXCEEDED 429 محاولات تسجيل دخول فاشلة كثيرة جداً
REGISTRATION_LIMIT_EXCEEDED 429 محاولات تسجيل كثيرة جداً

عند تلقي خطأ 429، راجع رؤوس الاستجابة:

Headers
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704067260
Retry-After: 45

أخطاء التحقق (400)

الرمز HTTP الوصف
VALIDATION_ERROR 400 حقل واحد أو أكثر لديه قيم غير صالحة
MISSING_REQUIRED_FIELD 400 حقل إلزامي مفقود
INVALID_EMAIL 400 تنسيق بريد إلكتروني غير صالح
INVALID_PHONE 400 تنسيق هاتف غير صالح
INVALID_DATE 400 تنسيق تاريخ غير صالح (يجب أن يكون YYYY-MM-DD)
INVALID_TIME 400 تنسيق وقت غير صالح (يجب أن يكون HH:MM)
DATE_IN_PAST 400 التاريخ قبل اليوم
DATE_TOO_FAR 400 التاريخ يتجاوز حد الحجز المسبق

مثال مع التفاصيل

JSON
{
    "success": false,
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "البيانات المرسلة غير صالحة",
        "details": {
            "email": ["تنسيق بريد إلكتروني غير صالح"],
            "telefono": ["هذا الحقل إلزامي"],
            "fecha": ["لا يمكن أن يكون التاريخ قبل اليوم"]
        }
    }
}

أخطاء الموارد (404)

الرمز HTTP الوصف
SERVICE_NOT_FOUND 404 الخدمة غير موجودة
PROFESSIONAL_NOT_FOUND 404 المحترف غير موجود
BOOKING_NOT_FOUND 404 الحجز غير موجود
CLIENT_NOT_FOUND 404 العميل غير موجود
CATEGORY_NOT_FOUND 404 الفئة غير موجودة

أخطاء الحجوزات

الرمز HTTP الوصف
SLOT_UNAVAILABLE 400 الموعد لم يعد متاحاً
PROFESSIONAL_NOT_WORKING 400 المحترف لا يعمل في هذا اليوم/الوقت
SERVICE_NOT_OFFERED 400 المحترف لا يقدم هذه الخدمة
BUSINESS_CLOSED 400 النشاط التجاري مغلق في هذا التاريخ
CANNOT_CANCEL 400 لا يمكن إلغاء الحجز (مضى بالفعل أو ملغى بالفعل)
CANCELLATION_DEADLINE_PASSED 400 انتهت مهلة الإلغاء
BOOKING_ALREADY_PAID 400 تم دفع الحجز بالفعل

أخطاء الدفع

الرمز HTTP الوصف
STRIPE_NOT_CONFIGURED 400 النشاط التجاري ليس لديه Stripe مُعدّ
INVALID_AMOUNT 400 مبلغ غير صالح (يجب أن يكون موجباً)
PAYMENT_FAILED 400 خطأ في معالجة الدفع
CARD_DECLINED 400 البطاقة مرفوضة
INSUFFICIENT_FUNDS 400 أموال غير كافية

أخطاء النقاط

الرمز HTTP الوصف
INSUFFICIENT_POINTS 400 ليس لديك نقاط كافية
POINTS_NOT_ENABLED 400 برنامج النقاط غير نشط
SERVICE_NOT_REDEEMABLE 400 هذه الخدمة غير قابلة للاستبدال بالنقاط

أخطاء الخادم (500)

الرمز HTTP الوصف
INTERNAL_ERROR 500 خطأ داخلي في الخادم
SERVICE_UNAVAILABLE 503 الخدمة غير متاحة مؤقتاً
أخطاء 500

إذا تلقيت أخطاء 500 بشكل متكرر، اتصل بالدعم على developers@salonbookit.com