استكشاف الأخطاء وإصلاحها

تظهر معظم المشكلات على شكل حالة HTTP وقيمة code في جسم الخطأ. ابحث عن الرمز أدناه؛ وفي الأخطاء القائمة الكاملة. الطلبات الفاشلة (أي 4xx أو 5xx) لا تُحاسَب أبدًا.

{ "error": { "message": "...", "type": "authentication_error", "code": "invalid_api_key" } }

401 invalid_api_key

المفتاح مفقود أو مشوَّه أو ملغى.

• أرسله بالشكل Authorization: Bearer sk-api14-.... تفعل OpenAI SDK ذلك انطلاقًا من apiKey / api_key؛ ومع curl تحقق من أن $API14_API_KEY مضبوط فعلًا في الصدفة التي تشغّل منها الأمر (يجب أن يطبع echo ${API14_API_KEY:0:9} القيمة sk-api14-).
• انتبه إلى علامات الاقتباس أو الأسطر الزائدة عندما يأتي المفتاح من ملف .env.
• قد يتغلب OPENAI_API_KEY المتروك في البيئة على المفتاح الذي تقصده. مرّر المفتاح صراحةً لاستبعاد ذلك.
• المفتاح الملغى يفشل فورًا. تُعرض المفاتيح مرة واحدة فقط، فإذا فقدت واحدًا فأنشئ مفتاحًا جديدًا في مفاتيح API والغِ القديم.

راجع المصادقة.

402 insufficient_balance

رصيدك بالدولار يساوي 0، أو (في الفيديو) أقل من التكلفة المقدَّرة للمهمة. تبقى الطلبات محجوبة إلى أن تضيف رصيدًا، وإعادة المحاولة لا تفيد.

• تحقق من الرصيد عبر GET /credits أو في الفوترة. راجع الرصيد ومعلومات المفتاح.
• أضف رصيدًا أو فعّل الشحن التلقائي. تضيف الخطط استهلاكًا مضمَّنًا إلى الرصيد نفسه كل شهر. راجع الأسعار والفوترة.
• في المهام الطويلة، تعامل مع هذا الرمز على أنه قاتل وتوقف، بدل ترك إعادات محاولة SDK تدور.

403 model_not_allowed أو plan_required

• model_not_allowed: للمفتاح قائمة نماذج مسموح بها لا تتضمن معرّف هذا النموذج. عدّل قائمة المفتاح في مفاتيح API، أو استخدم مفتاحًا بلا قائمة. لواحق المتغيرات تُحتسب: تأكد أن المعرّف الدقيق الذي ترسله مسموح به.
• plan_required: خطتك لا تشمل فئة هذا النموذج. الخطط القياسية تغطي كل الفئات؛ راجع خطتك في صفحة الأسعار.

404 model_not_found أو not_found

• model_not_found: معرّف النموذج غير معروف أو معطّل أو محذوف. تتضمن المعرّفات بادئة المزوّد: openai/gpt-5-mini لا gpt-5-mini. اعثر على المعرّف الدقيق عبر GET /models أو GET /models/{id} (دون مفتاح). راجع معرّفات النماذج والمتغيرات.
• not_found: المسار غير موجود، أو معرّف مهمة الفيديو أو التوليد ليس لك. يعني هذا غالبًا Base URL خاطئًا (انظر أدناه). كما قد يُعيد البحث عن عملية توليد فور الطلب 404 لبضع ثوانٍ إلى أن يظهر السجل.

Base URL خاطئ

عنوان Base URL هو بالضبط:

https://api14.com/api/v1

أخطاء شائعة:

خصوصيات المكتبات: تضيف ruby-openai الجزء v1 بنفسها، لذا يكون uri_base لديها https://api14.com/api (Ruby)؛ وتتوقع openai-go شرطة مائلة في النهاية، https://api14.com/api/v1/ (Go).

429 rate_limited

تجاوزت حد الطلبات في الدقيقة لمفتاحك أو خطتك (Free 5 وPro 100 وTeam 3,000 وEnterprise 3,000+). تتضمن الاستجابة Retry-After: 60.

• انتظر مدة Retry-After وأعد المحاولة بتراجع أُسّي مع عشوائية (jitter). تفعل OpenAI SDK الرسمية ذلك أصلًا (محاولتان افتراضيًا؛ ارفع maxRetries / max_retries).
• في الأعمال الكبيرة، نظّم إيقاع الطلبات بدل إطلاقها كلها دفعة واحدة، وضع عدة عناصر في طلب واحد. راجع دليل: المعالجة الدفعية.
• قد يأتي 429 أيضًا من المزوّد الأصلي، خصوصًا في متغيرات :free. استخدم النماذج الاحتياطية أو توجيه المزوّد لتوزيع الحمل.

429 daily_limit_reached

بلغ المفتاح حد الإنفاق اليومي بالدولار. إعادة المحاولة لا تفيد حتى يوم UTC التالي. ارفع الحد أو أزله في مفاتيح API إذا كانت حركة المرور متوقعة. تأكد أن منطق إعادة المحاولة لديك يميّز هذا الرمز عن rate_limited، وإلا ستواصل المهام إعادة المحاولة دون جدوى. راجع حدود الطلبات.

المهلات

قد تستغرق النماذج الكبيرة ونماذج الاستدلال والمخرجات الطويلة دقائق.

• افحص مهلة العميل لديك. مهلة Node وPython SDK الافتراضية 10 دقائق؛ أما عملاء HTTP الآخرون فغالبًا ما يستخدمون قيمًا افتراضية أقصر.
• استخدم البث للتوليدات الطويلة. تبدأ الرموز بالوصول خلال ثوانٍ، وتتوقف مهلات الاتصالات الخاملة في الوكلاء (proxies) وموازنات الحمل عن كونها مشكلة. راجع البث.
• اضبط max_tokens، ولنماذج الاستدلال استخدم جهد استدلال أقل.
• إذا مرّرت الطلبات عبر خادمك، فمهلات الوكيل لديه (مثل proxy_read_timeout في nginx، وافتراضيها 60 ثانية) تنطبق أيضًا.
• المهلة من جهتك لا تلغي التوليد لدى المزوّد، وقد يُحاسَب عليه. استخدم البحث عن عملية توليد مع معرّف الطلب للتحقق.

انقطاع البث أو توقفه مبكرًا

• افحص finish_reason في آخر جزء. القيمة "length" تعني بلوغ max_tokens؛ و"error" تعني فشل المزوّد في منتصف البث، ويحمل الجزء كائن error. أعد المحاولة، أو أضف بدائل.
• تقوم الوكلاء ومنصات serverless أحيانًا بتخزين استجابات SSE مؤقتًا أو قطعها. عطّل التخزين المؤقت (X-Accel-Buffering: no في nginx) وافحص أقصى مدة استجابة تسمح بها المنصة.
• إذا حلّلت البث بنفسك، فتجاهل أسطر التعليقات التي تبدأ بـ : (إبقاء الاتصال حيًا) وتوقف عند data: [DONE].
• إغلاق الاتصال مبكرًا لا يلغي الفاتورة: فقد يُنهي المزوّد التوليد على أي حال.

أخطاء CORS وتطبيقات المتصفح

لا تضع مفتاح API في كود المتصفح أو الجوال أبدًا. يستطيع أي شخص قراءته من الصفحة وإنفاق رصيدك. استدعِ api14 من الخادم الخلفي لديك واكشف للمتصفح نقطة النهاية الخاصة بك فقط:

// server.js (Node / Express)
app.post("/api/chat", async (req, res) => {
  const stream = await client.chat.completions.create({
    model: "openai/gpt-5-mini",
    messages: req.body.messages, // validate and limit this input
    stream: true,
  });
  for await (const chunk of stream) res.write(chunk.choices[0]?.delta?.content ?? "");
  res.end();
});

خطأ CORS في المتصفح أثناء التطوير سببه عادةً Base URL خاطئ (وصل الطلب إلى الموقع بدل API) أو ترويسة طلب مخصصة لا يسمح بها preflight في API؛ ونقل الاستدعاء إلى خادمك يحل الحالتين.

مشكلات إصدار SDK

• Python openai دون الإصدار 1.0 يستخدم openai.ChatCompletion.create وopenai.api_base. رقِّ الحزمة بـ pip install -U openai واستخدم العميل OpenAI(base_url=..., api_key=...).
• غياب chat.completions.parse: الإصدارات الأقدم من 1.x/4.x فيها فقط client.beta.chat.completions.parse. رقِّ الحزمة.
• أخطاء "معامل غير معروف" من SDK لحقول البوابة (provider وmodels وreasoning وplugins): مرّرها عبر extra_body في Python، أو خيار الجسم الإضافي المكافئ في SDK الأخرى. راجع التوافق مع OpenAI SDK.
• خطأ 400 من المزوّد مع رسالته: المعامل غير مدعوم من ذلك النموذج أو المزوّد. افحص supported_parameters للنموذج في النماذج، أو أضف provider: { "require_parameters": true }.