الأسئلة الشائعة
استكشاف الأخطاء وإصلاحها
أصلح مشكلات المصادقة والنماذج والبث والمهام وحدود المعدل بقائمة تحقق تبدأ من الأعراض.
ابدأ من العَرَض، ثم اتبع الإصلاح. تأتي معظم الأعطال من عنوان URL الأساسي أو المفتاح أو معرّف النموذج أو الرصيد.
جدول قائم على العَرَض
| العَرَض | السبب المحتمل | الإصلاح |
|---|---|---|
401 UNAUTHORIZED | مفتاح مفقود أو خاطئ أو مُبطَل أو غير مُرسل | أرسل Authorization: Bearer $FELO_API_KEY؛ أنشئ مفتاحًا جديدًا إذا أُبطل |
402 INSUFFICIENT_CREDITS | الرصيد لا يغطي الاستدعاء | أعد الشحن في Console Billing |
| 404 في كل طلب | عنوان URL الأساسي يتضمن مسارًا يضيفه endpoint بالفعل | استخدم https://openapi.felo.ai/api/v1 لعملاء OpenAI وhttps://openapi.felo.ai/api لعملاء Anthropic |
| 404 في نموذج واحد | معرّف النموذج غير عام، أو أن endpoint لا يخدمه | تحقق من معرّف النموذج في صفحة النماذج ومن مستندات endpoint |
خطأ 400 في model أو max_tokens | حقل مطلوب مفقود، أو النموذج لا يقبل شكل الطلب | أضف max_tokens لـMessages؛ أزل الحقول غير المدعومة |
| 429 | حد معدل، أو حد من مزوّد أعلى | اقرأ Retry-After؛ راجع الأخطاء والحدود وإعادة المحاولة |
| 5xx | عطل في المزوّد الأعلى أو الخدمة | أعد المحاولة مع تراجع تدريجي؛ أرفق request_id إذا استمر |
| البث يتصل لكنه لا يرسل شيئًا | وكيل يعمل كخازن مؤقت للاستجابة، أو محلّل الأحداث يتوقع تنسيقًا خاطئًا | اقرأ البث تدريجيًا؛ عطّل تخزين الاستجابة المؤقت في الوكيل |
| المهمة لا تنتهي أبدًا | endpoint استطلاع خاطئ، أو حالة نهائية لم تُعالَج | استطلع endpoint حالة المهمة نفسها وتوقف عند القيم النهائية |
| استدعاءات الأدوات مُتجاهلة | النموذج لا يعلن تلك القدرة | تحقق من supported_parameters في الكتالوج |
| Data API يعيد 404 | أُضيفت البادئة /v1/beta مرتين | استخدم المسار كما هو مكتوب في المرجع |
المصادقة
يعيد المفتاح المُبطَل رسالة تذكر بادئة المفتاح:
{
"status": 401,
"code": "UNAUTHORIZED",
"message": "API Key has been revoked (keyPrefix=...)"
}قائمة تحقق:
- الرأس هو
Authorization: Bearer <key>لـModel API وFelo APIs. - يقبل Data API أيضًا
X-API-Key: <key>. - المفتاح غير محاط بعلامات اقتباس، ولا يوجد سطر جديد زائد من متغيّر بيئة منسوخ.
- البيئة المنشورة تحتوي المتغيّر فعليًا؛ فقد يعمل مفتاح محليًا ويفتقد في الإنتاج.
- لم يُحذف المفتاح أو يُدوَّر. لا يمكن عرض المفتاح المحذوف أو المدوَّر مرة أخرى؛ أنشئ مفتاحًا جديدًا.
راجع المصادقة لإنشاء المفاتيح وحدودها.
مزالق عنوان URL الأساسي
| العميل | عنوان URL الأساسي الصحيح |
|---|---|
| OpenAI SDK | https://openapi.felo.ai/api/v1 |
| Anthropic SDK | https://openapi.felo.ai/api |
| endpoint النموذج الخام | https://openapi.felo.ai/api/v1/chat/completions أو /responses أو /messages |
| Data API | https://openapi.felo.ai/v1/beta |
Felo APIs /v2 | https://openapi.felo.ai/v2 |
خطأان شائعان:
- إضافة
/chat/completionsإلى عنوان URL أساسي يمدّه SDK بالفعل. - تعيين عنوان URL الأساسي لـAnthropic إلى
https://openapi.felo.ai/api/v1. تلحق SDK المسار/v1/messages، فيصبح الطلب/api/v1/v1/messages.
مشكلات معرّف النموذج
معرّفات النماذج هي المعرّفات العامة من الكتالوج، وليست الأسماء الداخلية لدى المزوّد الأعلى أو اسم عرض.
- ابحث عن المعرّف في صفحة النماذج أو في
GET /api/v1/models. - تأكد من أن النموذج يدعم البروتوكول الذي تستدعيه (
supported_protocols). - إذا ثبّتت قناة، فتأكد من أن تلك القناة منشورة وقابلة للتشغيل لذلك النموذج. القناة غير المتاحة ليست بديلًا احتياطيًا.
راجع القنوات وتوجيه المزوّد.
مشكلات البث
- عيّن
stream: trueفي نص الطلب، لا كمعامل استعلام. - اقرأ نص الاستجابة كتدفق. وانتظار الاستجابة الكاملة يُبطل فائدة البث.
- بعض الوكلاء ومنصات serverless تخزّن الاستجابات مؤقتًا. عطّل التخزين المؤقت للمسار الذي يمرّر الطلب.
- يبث Chat Completions الحقل
choices[0].delta، لاchoices[0].message. ويصل المحتوى النهائي عبر أجزاء كثيرة. - قد ينتهي البث دون حدث نهائي سليم إذا انقطع الاتصال. تعامل مع الاتصال المنقطع كاستجابة غير مكتملة.
مشكلات المهام غير المتزامنة
- استطلع endpoint الحالة الذي ينتمي إلى عائلة المهمة. تستخدم مسارات عمل Felo المسار
GET /v2/tasks/{task_id}/status؛ وتستخدم مهام الفيديو والصور endpoints التوليد الخاصة بها. - توقف عند كل حالة نهائية، بما في ذلك حالات الفشل وانتهاء الصلاحية، وليس عند النجاح فقط.
- تُتجاهل حاليًا ردود اتصال الفيديو والصور. لا تنتظر webhook.
- قد يكون عنوان URL للنتيجة قصير الصلاحية. اطلب عنوانًا جديدًا من endpoint الحالة إذا انتهت صلاحية التنزيل.
- تحقق من المهمة قبل إعادة الإرسال. إعادة إرسال مهمة قيد التشغيل تُنشئ نسخة مكررة، وتُحاسَب كلتاهما.
راجع المهام غير المتزامنة.
مشكلات Data API
- أبقِ مسار الطريقة الدقيق من مرجع Data API.
- نصوص الطلب خاصة بكل مزوّد. الحقل الذي يعمل مع مزوّد لا يُضمن أن يعمل مع آخر.
- قد يصل خطأ من المزوّد داخل استجابة 4xx برسالة خاصة بذلك المزوّد. سجّل
request_idونص الاستجابة.
تذكيرات أمنية
- لا تضع مفتاح API في شيفرة المتصفح أو حزمة تطبيق جوال أو مستودع عام. أبقِه على خادم ومرّر الطلبات عبره.
- لا تسجّل المفتاح الكامل. سجّل بادئة إذا كنت تحتاج إلى تمييزه.
- دوّر المفتاح فورًا إذا كان قد تسرّب.
قبل التواصل مع الدعم
اجمع:
- endpoint وطريقة HTTP.
- حالة HTTP و
codeوrequest_id. - معرّف النموذج أو معرّف المهمة.
- الطابع الزمني مع المنطقة الزمنية.
- نص طلب أدنى مع إزالة الأسرار.
أرسلها إلى الدعم مع بريد الحساب. لا تُضمّن مفتاح API الكامل.