الانتقال إلى المحتوى الرئيسي

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

عند وقوع خطأ، تُرجع API استجابة خطأ متسقة:
{
  "error": {
    "code": "invalid_request",
    "message": "The request body is missing required field 'email'",
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

رموز حالة HTTP

رمز الحالةالوصف
200نجاح
201تم الإنشاء
204لا يوجد محتوى (حذف ناجح)
400طلب غير صالح - معاملات غير صالحة
401غير مصرَّح - بيانات اعتماد غير صالحة أو مفقودة
403محظور - صلاحيات غير كافية
404غير موجود - المورد غير موجود
409تعارض - المورد موجود بالفعل
422كيان لا يمكن معالجته - خطأ في التحقق
429الكثير من الطلبات - تم تجاوز حد المعدل
500خطأ داخلي في الخادم

رموز الأخطاء الشائعة

أخطاء المصادقة

الرمزالوصف
invalid_tokenرمز الوصول غير صالح أو منتهي الصلاحية
missing_tokenلم يُقدَّم رأس authorization
insufficient_scopeيفتقر الرمز إلى الصلاحيات المطلوبة

أخطاء التحقق

الرمزالوصف
invalid_requestجسم الطلب مشوَّه
validation_errorفشل التحقق من حقل واحد أو أكثر
missing_fieldالحقل المطلوب مفقود

أخطاء الموارد

الرمزالوصف
not_foundالمورد المطلوب غير موجود
already_existsالمورد بهذا المعرّف موجود بالفعل
conflictالعملية تتعارض مع الحالة الحالية

أفضل ممارسات معالجة الأخطاء

1

تحقق من رمز الحالة أولاً

استخدم رمز حالة HTTP لتحديد الفئة العامة للخطأ.
2

حلّل استجابة الخطأ

استخرج error.code و error.message للمعالجة المحددة.
3

سجّل التفاصيل

خزّن استجابة الخطأ الكاملة لأغراض تصحيح الأخطاء.
4

اعرض رسائل سهلة للمستخدم

ترجم رموز الأخطاء إلى رسائل مناسبة لمستخدميك.

مثال على معالجة الأخطاء

try {
  const response = await fetch('https://api.rntor.com/v1/bookings', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiSecret}`,
      'X-Client-ID': clientId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(bookingData)
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.error.code) {
      case 'validation_error':
        // Handle validation errors
        break;
      case 'conflict':
        // Handle booking conflicts
        break;
      default:
        // Handle other errors
    }
  }
} catch (e) {
  // Handle network errors
}