خطأ Gemini ‏NOT_FOUND: المعنى والسبب والحل

السبب الأول: الملف الذي أشرت إليه اختفى

يعطي توثيق استكشاف الأخطاء لدى Google سبباً رسمياً واحداً للخطأ 404: الطلب أشار إلى ملف ليس موجوداً. وهذا يشمل الوسائط التي ترفقها بالمرجع بدل التضمين المباشر، أي الصور والصوت والفيديو. المراجع المرفوعة لا تعيش إلى الأبد؛ قد تنتهي صلاحيتها أو تُحذف، ولا شيء ينبّهك حين يختفي أحدها بهدوء. يبقى كودك يقدّم مقبضاً لمورد توقّف عن الوجود في مكان ما بين الرفع وهذا الاستدعاء.

أعد رفع الملف، واحفظ المرجع الجديد، ثم أرسل الطلب مرة أخرى. إذا كان التطبيق يحتفظ بالمراجع مدة طويلة، فتعامل معها على أنها مؤقتة: التقط الخطأ 404، وجدّد المرجع مرة واحدة، ثم أعد المحاولة. وإذا استمر الخطأ بعد الرفع، فتأكد من توافق معاملات الطلب مع إصدار الواجهة المستخدم.

السبب الثاني: النموذج تقاعد

قد يكون السبب تقاعد النموذج نفسه. أُوقف gemini-3-pro-preview في 9 مارس 2026، وعائلة gemini-2.0-flash في 1 يونيو 2026. ويحمل gemini-2.5-pro وgemini-2.5-flash تاريخ 16 أكتوبر 2026، الذي تنشره Google بصفته أبكر موعد محتمل للإيقاف. يعرض دليل إيقاف 2.5 Pro ومتتبّع النماذج الجدول الكامل.

البديلان المذكوران هما gemini-3.5-flash وgemini-3.1-pro-preview، وكلاهما أعلى سعراً من النموذج الذي يحل محله. في مسار Flash يرتفع سعر الإدخال من 0.30$ إلى 1.50$ لكل مليون توكن، والإخراج من 2.50$ إلى 9.00$. وفي مسار Pro يرتفع السعر من 1.25$/10$ إلى 2$/12$. احسب أثر الترحيل قبل تحويل حركة الإنتاج.

الاستجابة

إليك جسماً نموذجياً للخطأ 404، في شكل خطأ Google القياسي:

{
  "error": {
    "code": 404,
    "message": "The requested resource wasn't found.",
    "status": "NOT_FOUND"
  }
}

تفرّع على حقل status؛ يبقى NOT_FOUND ثابتاً بينما قد ينحرف نص الرسالة. لاحظ ما لا يخبرك به الجسم أبداً: أيّ السببين أصبت. التقويم يخبرك عادةً. خطأ 404 يبدأ صباح تاريخ إيقاف منشور هو تقاعد، لا خلل ملف.

الحل في الكود

لحالة الملف، غلّف الاستدعاء بحيث يُطلِق المرجع القديم إعادة رفع واحدة وإعادة محاولة واحدة بدل حلقة انهيار:

# Python (google-genai): أعد الرفع حين يُرجع مرجع ملف خطأ 404
from google import genai
from google.genai import errors

client = genai.Client()

def ask_about(path, prompt, model="gemini-3.5-flash"):
    ref = client.files.upload(file=path)
    try:
        return client.models.generate_content(model=model, contents=[ref, prompt])
    except errors.APIError as e:
        if e.code != 404:
            raise
        ref = client.files.upload(file=path)   # مقبض قديم: حدّثه
        return client.models.generate_content(model=model, contents=[ref, prompt])

لحالة التقاعد، تغيير الكود بأكمله هو سطر إعداد واحد:

# config.yaml
-  model: gemini-2.5-flash
+  model: gemini-3.5-flash

تبقى خطوة واحدة قبل إعادة توجيه حركة الإنتاج: أعد تسعير الفاتورة. هذا الفرق يرفع تكلفة الإدخال خمسة أضعاف بالسعر المعلن، وقفزة محتملة لروبوت دردشة قد تدمّر خط معالجة دفعي. اسحب الأرقام الحالية من صفحة تسعير Gemini 3.5 Flash، ومرّر أحجام التوكنز خاصتك عبر الحاسبة، واشحن الانتقال بالميزانية موقّعة سلفاً.