إذا لم يعمل شيء ما، فأسرع طريقة لمعرفة ما إذا كانت المشكلة من جهتك أم من جهتنا هي تشغيل نفس الطلب من أداة مختلفة.

نحو 9 من كل 10 تقارير تفيد بأن «واجهة API معطلة» يتبيّن أنها سببها رابط أساسي مُهيَّأ بشكل خاطئ، أو مفتاح API قديم، أو اسم نموذج خاطئ، أو شكل جسم الطلب مأخوذ من درس تعليمي يسبق الإصدار الحالي من SDK بثلاثة إصدارات.

اختبار ذاتي سريع

انسخ أمر curl هذا في الطرفية. استبدل YOUR_KEY بمفتاح API الخاص بك من Dashboard وشغّله. إذا حصلت على استجابة اكتمال طبيعية، فإن مفتاح API والشبكة والواجهة الخلفية لدينا جميعها تعمل بصحة جيدة — وأي خطأ يكون في كود العميل أو البيئة.

cURL

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

ℹ️

اختبار ذاتي سريع: لا تتوفر لديك طرفية؟ الصق نفس النموذج والـ prompt في Playground من Dashboard — نفس التأثير، لا إعداد مطلوب.

قائمة التحقق خطوة بخطوة

هل مفتاح API الخاص بك صالح؟

افتح Dashboard → API Keys وتأكد من أن المفتاح يطابق ما يستخدمه كودك. من الأخطاء الشائعة وجود مسافة بيضاء قبل البادئة "sk-air-" نتيجة النسخ واللصق.

العَرَض: 401 Unauthorized.

هل الرابط الأساسي صحيح؟

يجب أن يكون الرابط الأساسي https://api.airforce/v1 — وليس http، والمقطع /v1 مطلوب. تُغفل بعض الدروس التعليمية القديمة قبل اعتماد OpenAI هذا المسار أحيانًا.

العَرَض: 404 Not Found، أو توقف curl.

هل اسم النموذج مكتوب بشكل صحيح؟

معرّفات النماذج حساسة لحالة الأحرف. تفضل بزيارة صفحة Models أو استدعاء GET /v1/models للتأكد من المعرّف الدقيق. الخطأ الإملائي أو نموذج تم إيقافه يُعيد خطأً واضحًا بدلًا من «يعمل لكن بنتيجة خاطئة».

العَرَض: 400 unknown_model أو 404 model_not_found.

هل شكل جسم الطلب صحيح؟

تستخدم إكمالات المحادثة مصفوفة messages. تستخدم الصور prompt + n. يستخدم الصوت TTS الحقلَين input + voice. إرسال جسم بصيغة المحادثة إلى /v1/images/generations يُعيد 400 — سهل الوقوع فيه عند نسخ أجزاء بين الوثائق.

العَرَض: 400 مع ذكر الحقل المخالف في جسم الاستجابة.

هل تجاوزت حد المعدل أو الحصة؟

429 = طلبات كثيرة جدًا هذه الدقيقة. 402 = استُنفدت خطتك أو رصيدك. كلاهما يظهر في Dashboard. طلبات الخطة المجانية لها حدود منفصلة عن طلبات الخطة المدفوعة، لذا قد يستجيب نموذج مدفوع بشكل طبيعي بينما يُقيَّد نموذج مجاني.

العَرَض: 429 Too Many Requests أو 402 Payment Required.

هل النموذج يعمل الآن فعلًا؟

تحقق من صفحة Models — تظهر انقطاعات المزودين بوصف «متدهور» أو «عطل رئيسي». إذا كان نموذج واحد معطلًا بينما يعمل غيره، فهذه مشكلة من جانب المزود نتعامل معها بالتوجيه، وليست خطأ في العميل.

العَرَض: نموذج محدد يُعيد 5xx بينما تعمل نماذج أخرى.

ما الذي تعنيه رموز حالة HTTP

تحمل كل استجابة خطأ رمز حالة HTTP قياسيًا. معرفة ما يخبرك به كل رمز يُغنيك عن فتح تذكرة.


400	من جهتك	400 Bad Request — JSON مشوّه، أو حقل مطلوب مفقود، أو معامل غير معروف. صحّح جسم الطلب.
401	من جهتك	401 Unauthorized — مفتاح API مفقود أو غير صالح. تحقق من أن رأس Authorization يتضمن البادئة "Bearer ".
402	من جهتك	402 Payment Required — استُنفد الخطة أو رصيد الدفع حسب الاستخدام. اشترك أو أعد الشحن.
403	من جهتك	403 Forbidden — خطتك أو صلاحية المفتاح لا تسمح بهذا النموذج أو نقطة النهاية.
404	من جهتك	404 Not Found — نقطة نهاية أو معرّف نموذج غير معروف. تحقق من مسار URL وتهجئة النموذج.
413	من جهتك	413 Payload Too Large — يتجاوز الإدخال نافذة السياق للنموذج. قلّص الـ prompt.
429	من جهتك	429 Too Many Requests — تجاوزت حد المعدل (RPM أو RPD أو الحد اليومي للرموز). أبطئ الإرسال أو رقّي خطتك.
500	من جهتنا	500 Internal Server Error — خطأ من جهتنا. أبلغ عنه إذا استمر أكثر من دقيقة.
502	من جهتنا	502 Bad Gateway — الواجهة الخلفية في منتصف إعادة التشغيل (نُنشر عدة مرات يوميًا). انتظر 5–10 ثوانٍ وأعد المحاولة.
503	من جهتنا	503 Service Unavailable — فشل كل مزود خارجي لهذا النموذج في آنٍ واحد. أبلغ عنه إذا استمر أكثر من بضع دقائق.

💡

قاعدة أساسية: رموز 4xx تعني أن عميلك فعل شيئًا رفضه الخادم. رموز 5xx تعني أننا فشلنا في معالجة طلب صالح. يُسمّي جسم خطأ JSON في الاستجابة عادةً الحقل الذي أثار المشكلة.

متى تكون مشكلة فعلية في الكود

إذا نجح اختبار curl الذاتي أعلاه لكن نفس الطلب تمامًا من كودك لا يعمل، فالمشكلة في عميلك (أو المكتبة التي يستخدمها). أما إذا فشل الاختبار الذاتي نفسه بخطأ 5xx، أو أعاد 4xx برسالة لا تتطابق مع طلبك، فهذا يستحق الإبلاغ.

كيفية الإبلاغ بفعالية

افتح تذكرة دعم من Dashboard أو انشر في #support على Discord. أرفق:

رمز حالة HTTP الكامل وجسم الاستجابة (وكذلك رأس الاستجابة cf-ray إن وُجد).
الطابع الزمني التقريبي بتوقيت UTC.
اسم النموذج ونقطة النهاية التي استدعيتها.
أمر cURL بسيط يُعيد إنتاج المشكلة (أخفِ مفتاح API الحقيقي!).
ما إذا كان الاختبار الذاتي أعلاه يعمل لديك بنفس المفتاح.

ℹ️

كيفية الإبلاغ بفعالية: التذاكر التي تصلنا مع هذه التفاصيل تحصل على إجابة حقيقية من المحاولة الأولى. أما التذاكر التي تفتقر إليها، فتحتاج دائمًا إلى تبادل متعدد قبل أن نتمكن من المساعدة.

اسأل في #support على Discord

قبل الإبلاغ عن خطأ