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

تعيد كل واجهة Felo API نص خطأ JSON يتضمن رمز خطأ ثابتًا ومعرّف طلب. اقرأ حالة HTTP أولًا، ثم الرمز، ثم الرسالة.

غلاف الخطأ

تستخدم استجابات الإنتاج الحالية حالة HTTP كقيمة status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

تستخدم بعض أمثلة endpoints الأقدم status: "error" وسلسلة رمز مختلفة. اعتمد على حالة HTTP وcode، لا على الصياغة الدقيقة لـmessage.

الرموز الشائعة

تسرد مراجع endpoint الرموز الخاصة بذلك endpoint. ابدأ بـأخطاء Chat API أو بمرجع endpoint الذي تستدعيه.

endpoints توليد النماذج

تُرجع POST /api/v1/images/generations وPOST /api/v1/videos/generations أخطاء على مستوى endpoint ضمن غلاف OpenAI بدلًا من الغلاف أعلاه:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

يوجد معرّف الطلب في رأس الاستجابة X-Request-Id، وليس في النص. الطلب المرفوض لا ينشئ مهمة. بعد وجود المهمة، تصل معظم حالات الفشل كحالة مهمة نهائية ضمن استجابة 200 بدلًا من خطأ HTTP: تحقق من status بحثًا عن failed أو interrupted، ثم اقرأ error.message. راجع توليد الصور والمهام غير المتزامنة.

معرّفات الطلب

تتضمن نصوص أخطاء Felo request_id. سجّله مع endpoint وحالة HTTP ورمز الخطأ ومعرّف النموذج ومعرّف المهمة. لا تسجّل مفتاح API الكامل أبدًا.

يقبل Model API أيضًا رأس طلب اختياريًا X-Request-Id. عند إرساله، يُعاد إليك لأغراض التشخيص، ما يتيح ربط سجلاتك بطلب معين. إذا لم ترسله، فاستخدم request_id المعاد.

حدود المعدل

/v2/chat هو endpoint Felo الوحيد الذي له حدود معدل مفروضة وموثقة:

• لكل مفتاح API، نافذة دقيقة واحدة.
• لكل مستخدم، نافذة دقيقة واحدة.
• لكل مستخدم، نافذة ساعة واحدة.

يُستثنى المستخدمون الذين لديهم اشتراك Felo مدفوع ساري، بما في ذلك اشتراكات المؤسسات، ولا يتلقون رؤوس X-RateLimit-*. إذا تعذّر التحقق من حالة الاشتراك، تظل الحدود سارية.

لا توجد حاليًا حدود معدل مفروضة على endpoints أخرى ضمن /v2/**. قد تظل طلبات Model API محدودة من قِبل المزوّد الأعلى، وقد يظهر ذلك على هيئة 429.

لا تضع الحدود الرقمية مباشرة في الشيفرة. اقرأ الرؤوس في كل استجابة.

سياسة إعادة المحاولة

الحلقة الموصى بها:

1. أعد المحاولة فقط للطلبات المتكررة بأمان (idempotent) أو الآمنة التكرار.
2. استخدم تراجعًا أسّيًا: ابدأ بنحو ثانية واحدة، وضاعفها، وبحد أقصى 30 ثانية.
3. أضف تشويشًا عشوائيًا حتى لا يعيد العملاء المحاولة في تزامن تام.
4. توقف بعد عدد قليل من المحاولات وأظهر الخطأ.
5. عند 429، التزم بـRetry-After بدلًا من جدولك الخاص.

تسلسل تصحيح الأخطاء

1. تحقق من وجود المفتاح وأنه غير ملغى.
2. استدعِ GET /api/v1/models بالمفتاح نفسه لتأكيد المصادقة.
3. أرسل أصغر طلب صالح إلى endpoint المستهدف.
4. أضف البث أو الأدوات أو المدخلات الكبيرة واحدًا في كل مرة.
5. للعمل غير المتزامن، تحقق من حالة المهمة قبل إعادة الإرسال.

ذو صلة

• المصادقة
• القنوات وتوجيه المزوّد
• المهام غير المتزامنة
• استكشاف الأخطاء وإصلاحها