رموز الخطأ & استكشاف الأعطال

تعرّف على أخطاء API الشائعة وأسبابها وكيفية حلها. استخدم هذا الدليل لتصحيح المشكلات وتطبيق معالجة أخطاء فعّالة في تطبيقاتك.

مرجع سريع — جميع رموز الخطأ

Status الاسم الخطورة وصف موجز
200 OK Info الطلب ناجح، الاستجابة جاهزة.
401 Unauthorized Error مفتاح API مفقود أو غير صالح أو منتهي الصلاحية.
402 Payment Required Error رصيد غير كافٍ لإتمام الطلب.
403 Forbidden Warning مصادق عليه لكن بدون صلاحيات كافية.
404 Not Found Warning النموذج المطلوب غير موجود أو مسار API خاطئ.
422 Unprocessable Entity Warning فشل التحقق — حقول مفقودة أو قيم غير صالحة.
429 Too Many Requests Error تجاوز حد معدل الطلبات، انتظر retry_after.
500 Internal Server Error Critical خطأ غير متوقع من جانب الخادم، أعد المحاولة.

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

عند مواجهة خطأ، تُعيد واجهة LLM Resayil API استجابة JSON تصف ما حدث. فهم كيفية تحليل هذه الاستجابات ضروري لبناء تطبيقات قوية.

تتبع جميع استجابات الخطأ هذا التنسيق الموحد:

JSON
{ "error": { "message": "Human-readable error message", "code": 401 } }

تحتوي بعض الأخطاء — كأخطاء التحقق (422) — على حقل إضافي errors يوفر تفاصيل التحقق لكل حقل:

JSON — 422 Validation
{ "error": { "message": "Validation failed", "code": 422 }, "errors": { "model": ["The model field is required."], "messages": ["The messages field must be an array."] } }

أمثلة تفصيلية لاستجابات الأخطاء

401 Unauthorized Error

مفتاح API مفقود أو غير صالح في رأس Authorization.

HTTP / JSON — 401
HTTP/1.1 401 Unauthorized { "error": { "message": "Unauthenticated.", "code": 401 } }
  • تأكد من أن مفتاح API صحيح ومنسوخ بدون مسافات إضافية
  • تأكد من أن تنسيق رأس Authorization هو: Authorization: Bearer YOUR_KEY
  • أنشئ مفتاحاً جديداً إذا اعتقدت أن المفتاح الحالي قد اختُرق
  • تحقق من أن المفتاح لم يُلغَ من لوحة التحكم
402 Payment Required Error

استُنفد رصيد حسابك. يجب إضافة رصيد للمتابعة.

HTTP / JSON — 402
HTTP/1.1 402 Payment Required { "error": { "message": "Insufficient credits. Please top up your balance to continue.", "code": 402 } }
  • انتقل إلى لوحة التحكم واشترِ رصيداً إضافياً عبر /billing/plans
  • تحقق من رصيدك الحالي عبر نقطة النهاية GET /api/billing/subscription
  • فكّر في الترقية إلى خطة اشتراك لتجنب انقطاع الخدمة
403 Forbidden Warning

تمت المصادقة لكن الحساب لا يملك الصلاحيات الكافية للوصول إلى المورد المطلوب.

HTTP / JSON — 403
HTTP/1.1 403 Forbidden { "error": { "message": "You do not have permission to access this resource.", "code": 403 } }
  • تحقق من حالة حسابك في لوحة التحكم — قد يكون موقوفاً
  • تأكد من أن اشتراكك لا يزال نشطاً
  • تواصل مع الدعم إذا اعتقدت أن هذا خطأ
404 Not Found Warning

النموذج المطلوب غير موجود، أو مسار API غير صحيح.

HTTP / JSON — 404
HTTP/1.1 404 Not Found { "error": { "message": "Model not found.", "code": 404 } }
  • تحقق من اسم النموذج المستخدم في حقل model بطلبك
  • راجع قائمة النماذج المتاحة في لوحة التحكم
  • تأكد من صحة عنوان URL للطلب
422 Unprocessable Entity Warning

فشل التحقق من صحة الطلب. يتضمن الرد كائن errors يصف كل حقل به خطأ.

HTTP / JSON — 422
HTTP/1.1 422 Unprocessable Entity { "error": { "message": "Validation failed", "code": 422 }, "errors": { "model": ["The model field is required."], "messages": ["The messages field must be an array."] } }
  • افحص كائن errors لتحديد الحقول ذات المشكلات
  • تأكد من تضمين جميع الحقول المطلوبة: model وmessages
  • تأكد من أن messages مصفوفة من الكائنات التي تحتوي على role وcontent
  • تحقق من صحة بناء JSON قبل الإرسال
429 Too Many Requests Error

تجاوزت حد معدل الطلبات. تتضمن الاستجابة حقل retry_after يحدد عدد الثواني اللازمة للانتظار.

HTTP / JSON — 429
HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 20 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1741305600 { "error": { "message": "Rate limit exceeded", "code": 429 }, "retry_after": 45 }
  • انتظر عدد الثواني المحدد في retry_after قبل إعادة المحاولة
  • طبّق انتظاراً تدريجياً أسياً للمحاولات التلقائية
  • تحقق من حدود مستواك وفكّر في الترقية إذا تكررت المشكلة
  • طبّق تقنيناً من جانب العميل للبقاء ضمن حصتك
500 Internal Server Error Critical

حدث خطأ غير متوقع من جانب الخادم. هذه الأخطاء نادرة وعادةً مؤقتة.

HTTP / JSON — 500
HTTP/1.1 500 Internal Server Error { "error": { "message": "An unexpected error occurred. Please try again later.", "code": 500 } }
  • أعد المحاولة بعد بضع ثوانٍ
  • طبّق انتظاراً تدريجياً أسياً للمحاولات التلقائية
  • إذا استمر الخطأ، تواصل مع الدعم

قائمة التحقق للتصحيح

عند مواجهة أي خطأ، اعمل عبر هذه القائمة لتحديد المشكلة وحلها:

لجميع الأخطاء

  • تأكد من صحة مفتاح API وتنسيقه الصحيح في رأس Authorization
  • تأكد من استخدام طريقة POST وليس GET
  • تأكد من ضبط رأس Content-Type على application/json
  • تحقق من صحة بناء JSON في طلبك

لأخطاء 401 و 403

  • تأكد من أن حسابك نشط وغير موقوف
  • تحقق من أن مفتاح API لم يُلغَ
  • تأكد من أن اشتراكك لا يزال ساري المفعول
  • تحقق من وجود رصيد كافٍ (الخطأ 402)

لأخطاء 422

  • تضمّن جميع الحقول المطلوبة: model و messages
  • تأكد من أن اسم النموذج صالح وموجود في حسابك
  • تأكد من أن messages مصفوفة من الكائنات التي تحتوي على role و content
  • استخدم حقل errors في الاستجابة لتحديد الحقل المشكل

لأخطاء 429

  • راقب رأس X-RateLimit-Remaining في استجاباتك
  • طبّق منطق إعادة المحاولة مع الانتظار التدريجي
  • قلّل تكرار طلباتك
  • فكّر في الترقية إلى مستوى أعلى للحصول على حدود أكبر

لأخطاء 500

  • أعد المحاولة بعد 5–10 ثوانٍ
  • طبّق انتظاراً تدريجياً أسياً لعدة محاولات
  • تواصل مع الدعم إذا استمرت الأخطاء

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

1. احلل استجابات الأخطاء دائماً

لا تكتفِ بالتحقق من رمز الحالة HTTP. حلّل JSON الخاص باستجابة الخطأ لفهم ما حدث وتقديم تغذية راجعة مفيدة للمستخدمين.

2. طبّق منطق إعادة المحاولة

استخدم انتظاراً تدريجياً أسياً مع عشوائية للأخطاء القابلة للمحاولة (429، 500). راجع دليل حدود المعدل للتفاصيل.

3. سجّل الأخطاء للتصحيح

سجّل استجابات الأخطاء كاملةً مع رموز الحالة ورموز الأخطاء ومعرّفات الطلبات. هذا يجعل التصحيح أسرع بكثير.

4. قدّم رسائل سهلة الفهم للمستخدمين

لا تعرض رسائل الخطأ الخام للمستخدمين. حوّل رموز الأخطاء إلى رسائل ودية وقدّم إرشادات عملية.

5. راقب حدود المعدل بشكل استباقي

تابع X-RateLimit-Remaining في الاستجابات وقلّل الطلبات قبل الوصول إلى الحد.

6. اضبط مهلات انتظار مناسبة

اضبط مهلات الطلبات على 30 ثانية على الأقل للسماح للنماذج الأبطأ وزمن الشبكة.

موارد ذات صلة

انتهيت من التوثيق؟

أنت جاهز للبدء في البناء باستخدام LLM Resayil.

أنشئ حساباً مجانياً ←