معالجة الأخطاء | Developer API

افهم كيف يبلغ Fit It On API عن الأخطاء، بما في ذلك حالات الفشل على مستوى واجهة برمجة التطبيقات وأخطاء وقت التشغيل غير المتزامنة.

يساعدك فهم كيفية إبلاغ واجهة برمجة التطبيقات عن الأخطاء على الاستجابة بسرعة والحفاظ على مرونة تكاملك. تصنف واجهة برمجة تطبيقات Fit It On الأخطاء إلى مرحلتين متميزتين:

أخطاء على مستوى واجهة برمجة التطبيقات (API-level errors): تم رفض الطلب فورًا قبل إصدار معرف التنبؤ.
أخطاء وقت التشغيل (Runtime errors): تم قبول الطلب وتم إرجاع معرف التنبؤ، لكن عملية الإنشاء فشلت أثناء المعالجة غير المتزامنة.

أخطاء على مستوى واجهة برمجة التطبيقات

تحدث الأخطاء على مستوى واجهة برمجة التطبيقات بشكل متزامن. عندما تقوم بإجراء طلب POST إلى /v1/run، أو طلب GET إلى /v1/status/{id}، يتحقق الخادم من صحة الطلب قبل البدء بأي عمل مكثف في الخلفية.

إذا فشل التحقق من الصحة، تُرجع واجهة برمجة التطبيقات حالة خطأ HTTP (مثل 400، 401)، ويحتوي استجابة JSON على رسالة error و code سلسلة نصية محددة.

{
  "error": "Invalid request payload. Expected { model_name, inputs }",
  "code": "BadRequest"
}

رموز الأخطاء القياسية

الرمز	الخطأ	السبب	كيفية الإصلاح
400	BadRequest	تنسيق طلب غير صالح أو اسم نموذج غير مدعوم	تحقق من بنية JSON، وتأكد من صحة `model_name`، وتحقق من توفير جميع المدخلات المطلوبة.
401	UnauthorizedAccess	مفتاح API غير صالح أو مفقود	تحقق من صحة رأس `Authorization: Bearer YOUR_API_KEY` وأن المفتاح نشط.
402	OutOfCredits	لا توجد أرصدة API للمطورين متبقية	أعد شحن أرصدتك في لوحة تحكم Fit It On قبل إعادة المحاولة.
403	Forbidden	وصول غير مصرح به إلى التنبؤ	أنت تحاول التحقق من حالة تنبؤ تم إنشاؤه بواسطة مفتاح مطور مختلف.
404	NotFound	التنبؤ غير موجود	تأكد من صحة معرف التنبؤ عند استقصاء نقطة نهاية الحالة.
413	PayloadTooLarge	الحمولة تتجاوز الحدود	تأكد من أن صور الإدخال أقل من 25 ميجابايت واستخدم دقة معقولة.
500	InternalServerError	خطأ من جانب الخادم	أعد المحاولة مع التراجع. اتصل بالدعم إذا استمرت المشكلة.

[!TIP] إعادة المحاولة والتطابق إذا واجهت خطأ على مستوى واجهة برمجة التطبيقات، يمكنك إعادة محاولة نفس الحمولة بأمان بمجرد حل المشكلة. نظرًا لرفض الطلب فورًا، لم يتم خصم أي أرصدة ولا يوجد خطر من المعالجة المزدوجة.

أخطاء وقت التشغيل

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

نظرًا لأن نماذج الإنشاء غير متزامنة بشكل كبير، ستكتشف هذه الأخطاء أثناء استقصاء نقطة نهاية /v1/status/{id}. إذا فشلت مهمة في الخلفية، تُرجع نقطة النهاية 200 OK HTTP (لأن طلب الاستقصاء نفسه كان ناجحًا)، ولكن حقل status داخل الحمولة سيكون "failed".

ستتضمن الاستجابة معرف التنبؤ وكائن error يوضح بالتفصيل ما حدث من خطأ، بما في ذلك name مصنف و message وصفي.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "failed",
  "output": null,
  "error": {
    "name": "ImageLoadError",
    "message": "Failed to load input image: URL returned 404"
  },
  "created_at": "2024-05-15T12:00:00Z",
  "updated_at": "2024-05-15T12:00:10Z"
}

أخطاء وقت التشغيل الشائعة

تقع معظم مشكلات وقت التشغيل ضمن عدد قليل من الفئات المشتركة عبر نماذجنا:

الفئة	رسائل الخطأ الشائعة	كيفية الإصلاح
خطأ تحميل الصورة	`Failed to fetch image`, `Invalid image URL`	تأكد من أن عناوين URL المقدمة عامة ويمكن الوصول إليها بدون مصادقة. بالنسبة لـ Base64، تأكد من أنها تتضمن بادئة نوع MIME الصحيحة.
التحقق من صحة الإدخال	`Image resolution too small`, `Missing required parameter`	تأكد من أن أصول الإدخال الخاصة بك تلبي الحد الأدنى للأبعاد والمتطلبات للنموذج المحدد.
الإشراف على المحتوى	`NSFW content detected`, `Safety block triggered`	استبدل أو اضبط صورة الإدخال أو المطالبة النصية للامتثال لمرشحات الأمان.
خطأ في خط الأنابيب	`Generation failed`, `Server error`	حدث فشل غير متوقع في مجموعة وحدات معالجة الرسومات. أعد محاولة الطلب مع التراجع.

[!NOTE] استرداد الأرصدة عند الفشل التنبؤات الفاشلة لا تستهلك أرصدة. إذا فشلت عملية إنشاء أثناء وقت التشغيل (على سبيل المثال، بسبب Image Load Error أو Pipeline Error)، يتم استرداد الأرصدة المخصومة في بداية الطلب تلقائيًا إلى رصيد المطور الخاص بك.

أخطاء خاصة بنقطة النهاية

تحتوي بعض النماذج على قواعد تحقق صارمة وخاصة بسير العمل يتم تشغيلها أثناء الإنشاء:

التحكم في الوضعية (Pose Control): سيفشل إذا لم يتم اكتشاف جسم بشري في الصورة المستهدفة.
التجربة الافتراضية (Virtual Try-On): سيفشل إذا لم يتمكن من اكتشاف قطعة ملابس صالحة في صورة قطعة الملابس.
إنشاء النموذج (Model Generation): سيفشل إذا كانت الصورة المرجعية للوجه المقدمة لا تحتوي على وجه واضح وغير محجوب.

إذا استمررت في رؤية حالات فشل وقت التشغيل بعد مطابقة المدخلات مع الوثائق، يرجى الاتصال بالدعم مع معرف التنبؤ الخاص بك حتى نتمكن من التحقيق.