رموز الأخطاء

عندما يفشل طلب، تُرجع واجهة API استجابة خطأ JSON مع code قابل للقراءة آلياً وmessage قابل للقراءة بشرياً:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

حقل code ثابت وآمن للمطابقة في منطق تطبيقك. حقل message قد يتغير بمرور الوقت وهو مخصص للتسجيل وتصحيح الأخطاء.

مرجع رموز الأخطاء

الرمز	حالة HTTP	الوصف	قابل لإعادة المحاولة	الحل
UNAUTHORIZED	401	رمز مصادقة مفقود أو غير صالح أو منتهي الصلاحية	لا	تحقق من أن مفتاح API صالح وغير منتهي
KEY_EXPIRED	401	تجاوز مفتاح API تاريخ انتهاء صلاحيته	لا	أنشئ مفتاح API جديداً في لوحة التحكم أو عبر API
FORBIDDEN	403	مصادق عليه لكن غير مفوض لهذا المورد	لا	يمكنك فقط الوصول إلى مواردك الخاصة
NOT_FOUND	404	المورد المطلوب غير موجود	لا	تحقق من صحة معرّف المورد
VALIDATION_ERROR	400	فشل جسم الطلب في التحقق من المخطط	لا	تحقق من الحقول المطلوبة وأنواع البيانات تطابق المخطط
INVALID_MIME_TYPE	400	الملف المرفوع بنوع MIME غير مدعوم	لا	استخدم نوع ملف مدعوم (PDF أو DOCX)
FILE_TOO_LARGE	400	الملف المرفوع يتجاوز حد الحجم 10 ميجابايت	لا	قلّل حجم الملف أو قسّمه إلى مستندات أصغر
MAX_KEYS_REACHED	400	تم الوصول إلى الحد الأقصى وهو 10 مفاتيح API نشطة	لا	ألغِ المفاتيح غير المستخدمة قبل إنشاء مفاتيح جديدة
USAGE_LIMIT_EXCEEDED	429	تم الوصول إلى حد الاستخراج الشهري	لا	قم بترقية خطتك أو انتظر فترة الفوترة التالية
INTERNAL_ERROR	500	خطأ غير متوقع في الخادم	نعم	أعد المحاولة مع تراجع أسي. إذا استمر، تواصل مع الدعم
NOT_CONFIGURED	501	خدمة مطلوبة من جانب الخادم غير مكوّنة	لا	تواصل مع الدعم -- هذا يشير إلى مشكلة في تكوين الخادم
EXTRACTION_FAILED	502	فشلت معالجة استخراج الذكاء الاصطناعي	نعم	أعد المحاولة -- قد تكون مشكلة مؤقتة. تحقق من صحة ملف PDF وقابليته للقراءة
EXTRACTION_PARSE_ERROR	502	أرجع الذكاء الاصطناعي استجابة لا يمكن تحليلها كـ JSON	نعم	أعد المحاولة -- قد ينتج الذكاء الاصطناعي مخرجات صالحة في محاولة لاحقة

الأخطاء القابلة لإعادة المحاولة

فقط رموز الأخطاء التالية يجب إعادة محاولتها:

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

عند إعادة المحاولة، استخدم تراجعاً أسياً يبدأ من ثانية واحدة، بحد أقصى 3 محاولات:

المحاولة	التأخير
المحاولة الأولى	ثانية واحدة
المحاولة الثانية	ثانيتان
المحاولة الثالثة	4 ثوانٍ

إذا استمر فشل الطلب بعد 3 محاولات، سجّل الخطأ وأظهره للمستخدم أو نظام المراقبة الخاص بك.

للحصول على دليل كامل حول تنفيذ منطق إعادة المحاولة، راجع معالجة الأخطاء.

ملخص رموز حالة HTTP

الحالة	المعنى
200	نجاح -- اكتمل الطلب بنجاح
400	طلب سيء -- خطأ في التحقق أو نوع ملف غير صالح أو ملف كبير جداً أو تم الوصول إلى حد المفاتيح
401	غير مصرح به -- فشلت المصادقة (رمز مفقود أو غير صالح أو منتهي الصلاحية)
403	محظور -- مصادق عليه لكن غير مفوض للمورد المطلوب
404	غير موجود -- المورد المطلوب غير موجود
429	طلبات كثيرة جداً -- تم تجاوز حد استخدام الاستخراج الشهري
500	خطأ داخلي في الخادم -- فشل غير متوقع على جانب الخادم
501	غير مُنفّذ -- خدمة مطلوبة من جانب الخادم غير مكوّنة
502	بوابة سيئة -- فشل استخراج أو تحليل الذكاء الاصطناعي