رموز الخطأ

خطأ 400: API key not valid. Please pass a valid API key.

إذا تلقّيت الخطأ 400 الذي يشير إلى API key not valid. Please pass a valid API key.، يعني ذلك عادةً أنّ مفتاح واجهة برمجة التطبيقات في ملف/عنصر إعدادات Firebase غير متوفّر أو لم يتم إعداده لاستخدامه مع تطبيقك و/أو مشروع Firebase.

تأكَّد من أنّ مفتاح واجهة برمجة التطبيقات المُدرَج في ملف/عنصر إعدادات Firebase يتطابق مع مفتاح واجهة برمجة التطبيقات لتطبيقك. يمكنك عرض جميع مفاتيح واجهة برمجة التطبيقات في لوحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد في وحدة تحكّم Google Cloud.

إذا تبيّن لك أنّهما لا يتطابقان، عليك الحصول على ملف/عنصر إعداد جديد على Firebase، ثم استبدال الملف/العنصر المتوفّر في تطبيقك بملف/عنصر الإعداد الجديد الذي يجب أن يحتوي على مفتاح صالح لواجهة برمجة التطبيقات لتطبيقك ومشروع Firebase.

خطأ 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

إذا كنت تحاول إرسال طلب متعدد الوسائط باستخدام عنوان URL Cloud Storage for Firebase، قد يظهر لك الخطأ 400 التالي:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.

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

في ما يلي الحلّ البديل لإصلاح مشروعك وتوفير وكلاء الخدمة هؤلاء بشكل صحيح حتى تتمكّن من تضمين عناوين URL Cloud Storage for Firebase في طلباتك المتعدّدة الوسائط. يجب أن تكون مالكًا للمشروع، ويجب إكمال هذه المجموعة من المهام مرة واحدة فقط لكل مشروع.

1. الوصول والمصادقة باستخدام gcloud CLI
   أسهل طريقة لإجراء ذلك هي من Cloud Shell. يمكنك الاطّلاع على مزيد من المعلومات في مستندات Google Cloud.

2. إذا طُلب منك ذلك، اتّبِع التعليمات المعروضة في نافذة الأوامر لتنفيذ gcloud CLI على مشروعك على Firebase.

   ستحتاج إلى رقم تعريف مشروع Firebase، ويمكنك العثور عليه في أعلى صفحة settings إعدادات المشروع في وحدة تحكّم Firebase.

3. وفِّر وكلاء الخدمة المطلوبين في مشروعك من خلال تنفيذ الأمر التالي:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"  https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
   

4. انتظِر بضع دقائق للتأكّد من توفير وكلاء الخدمة، ثم أعِد محاولة إرسال طلبك المتعدّد الوسائط الذي يتضمّن عنوان URL الخاص بـ Cloud Storage for Firebase.

إذا استمر ظهور هذا الخطأ بعد الانتظار لعدة دقائق، يُرجى التواصل مع فريق دعم Firebase.

الخطأ 403: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check

إذا تلقّيت رسالة الخطأ 403 - PERMISSION_DENIED التي تشير إلى To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check، يعني ذلك أنّ طلبك لا يتضمّن رمز App Check صالحًا وأنّك تحاول الوصول إلى نموذج يُساء استخدامه بشكل شائع.

تم تحديد بعض النماذج التوليدية على أنّها شائعة الاستخدام من قِبل الجهات المسيئة.

بما أنّك لم تفعّل App Check لـ Firebase AI Logic، فإنّ مشروعك معرّض لإساءة استخدام هذه النماذج. للمساعدة في حماية المطوّرين، يحظر Firebase الوصول إلى هذه النماذج ما لم يتضمّن الطلب رمزًا مميزًا صالحًا App Check (ما يعني أنّه يتم فرض App Check على Firebase AI Logic).

إذا أردت الوصول إلى النموذج الذي عرض الخطأ، اتّبِع الخطوات التالية:

1. إعداد App Check لـ "Firebase AI Logic" بالنسبة إلى التطوير المحلي، تأكَّد من إعداد App Check مقدّم خدمة تصحيح الأخطاء.

   يُعدّ فرض App Check أمرًا بالغ الأهمية للمساعدة في حماية نماذج Gemini API وGemini من إساءة الاستخدام، ويجب فرضه لإزالة هذا الخطأ.

2. أعِد إرسال الطلب من تطبيقك إلى Firebase AI Logic.

   سيرسل هذا الطلب رمزًا مميزًا صالحًا App Check، ولن يظهر لك الخطأ 403 - PERMISSION_DENIED بعد ذلك.

3. قبل طرح تطبيقك للمستخدمين النهائيين، عليك إعداد موفّر خدمة إثبات صحة في بيئة الإنتاج (مثل App Attest أو Play Integrity أو reCAPTCHA Enterprise) حتى يتمكّن المستخدمون النهائيون من الوصول إلى ميزة الذكاء الاصطناعي عند فرض App Check.

الخطأ 403: PERMISSION_DENIED: Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check

إذا تلقّيت الخطأ 403 - PERMISSION_DENIED الذي يشير إلى Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check، يعني ذلك أنّه تم تحديد مشروعك على Firebase على أنّه غير نشط وأنّك لم تفعّل App Check في Firebase AI Logic.

"المشاريع غير النشطة" هي المشاريع التي تم تفعيل Firebase AI Logic فيها، ولكن لم يتم استخدام Firebase AI Logic فيها مؤخرًا.

بما أنّك لم تفعّل App Check في Firebase AI Logic، فإنّ مشروعك معرّض لإساءة استخدام Gemini API. للمساعدة في حماية مشروعك، أوقفت Firebase استخدام Firebase AI Logic إلى أن تفرض App Check على Firebase AI Logic.

عندما تكون مستعدًا لبدء استخدام Firebase AI Logic مرة أخرى، اتّبِع الخطوات التالية:

1. إعداد App Check لـ "Firebase AI Logic" بالنسبة إلى التطوير المحلي، تأكَّد من إعداد App Check مقدّم خدمة تصحيح الأخطاء.

   يُعدّ فرض App Check أمرًا بالغ الأهمية للمساعدة في حماية نماذج Gemini API وGemini من إساءة الاستخدام، ويجب فرضه لإزالة هذا الخطأ.

2. أعِد إرسال الطلب من تطبيقك إلى Firebase AI Logic.

   سيرسل هذا الطلب رمزًا مميزًا صالحًا App Check، ولن يظهر لك الخطأ 403 - PERMISSION_DENIED بعد ذلك.

3. إذا كنت تفرض استخدام App Check وظهر لك هذا الخطأ، تحقّق مما إذا كانت ميزة الحماية من إعادة التشغيل مفعّلة في Firebase AI Logic (بما في ذلك في وضع "المراقبة فقط").

   عند تفعيل ميزة "الحماية من إعادة التشغيل"، تُحتسب الرموز المميزة ذات الاستخدام المحدود فقط كرموز تم التحقّق منها في Firebase AI Logic، ولا تؤدي رموز الجلسات العادية إلى إزالة هذا الخطأ. يمكنك إما تفعيل الرموز المميزة ذات الاستخدام المحدود في تطبيقك أو إيقاف ميزة "الحماية من إعادة التشغيل" لـ Firebase AI Logic وإعادة إرسال طلب والانتظار لمدة يوم تقريبًا قبل إعادة تفعيل ميزة "الحماية من إعادة التشغيل" (تتم إعادة تقييم نشاط المشروع يوميًا).

4. قبل طرح تطبيقك للمستخدمين النهائيين، عليك إعداد موفّر خدمة إثبات صحة في بيئة الإنتاج (مثل App Attest أو Play Integrity أو reCAPTCHA Enterprise) حتى يتمكّن المستخدمون النهائيون من الوصول إلى ميزة الذكاء الاصطناعي عند فرض App Check.

الخطأ 403: PERMISSION_DENIED: The caller does not have permission.

إذا تلقّيت رمز الخطأ 403 الذي يشير إلى PERMISSION_DENIED: The caller does not have permission.، يعني ذلك عادةً أنّ مفتاح واجهة برمجة التطبيقات في ملف/عنصر إعدادات Firebase يخصّ مشروعًا آخر على Firebase.

تأكَّد من أنّ مفتاح واجهة برمجة التطبيقات المُدرَج في ملف/عنصر إعدادات Firebase يتطابق مع مفتاح واجهة برمجة التطبيقات لتطبيقك. يمكنك عرض جميع مفاتيح واجهة برمجة التطبيقات في لوحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد في وحدة تحكّم Google Cloud.

إذا تبيّن لك أنّهما لا يتطابقان، عليك الحصول على ملف/عنصر إعداد جديد على Firebase، ثم استبدال الملف/العنصر المتوفّر في تطبيقك بملف/عنصر الإعداد الجديد الذي يجب أن يحتوي على مفتاح صالح لواجهة برمجة التطبيقات لتطبيقك ومشروع Firebase.

الخطأ 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.

إذا تلقّيت الخطأ 403 الذي يعرض الرسالة Requests to this API firebasevertexai.googleapis.com ... are blocked.، يعني ذلك عادةً أنّ مفتاح واجهة برمجة التطبيقات في إعدادات Firebase في تطبيقك يتضمّن قيودًا تمنعه من طلب البيانات من واجهة برمجة التطبيقات المطلوبة.

لإصلاح هذه المشكلة، عليك تعديل القيود المفروضة على مفتاح واجهة برمجة التطبيقات في Google Cloud console لتضمين واجهة برمجة التطبيقات المطلوبة. بالنسبة إلى Firebase AI Logic، عليك التأكّد من تضمين Firebase AI Logic API (firebasevertexai.googleapis.com) في قائمة واجهات برمجة التطبيقات المحدّدة التي يمكن طلب بياناتها باستخدام مفتاح واجهة برمجة التطبيقات.

اتبع هذه الخطوات:

1. في وحدة تحكّم Google Cloud، افتح اللوحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

2. اختَر مفتاح واجهة برمجة التطبيقات الذي تم ضبط تطبيقك لاستخدامه (على سبيل المثال، "مفتاح iOS" لتطبيق iOS).

3. في صفحة تعديل مفتاح واجهة برمجة التطبيقات، ابحث عن قسم القيود المفروضة على واجهة برمجة التطبيقات.

4. تأكَّد من اختيار الخيار تقييد المفتاح. إذا لم يكن كذلك، يعني هذا أنّ مفتاحك غير مقيّد، ومن المحتمل ألا يكون هذا هو مصدر الخطأ.

5. في القائمة المنسدلة واجهات برمجة التطبيقات المحدّدة، ابحث عن Firebase AI Logic API واختَره لإضافته إلى قائمة واجهات برمجة التطبيقات المحدّدة التي يمكن استدعاؤها باستخدام مفتاح واجهة برمجة التطبيقات.

6. انقر على حفظ.

   قد يستغرق تطبيق التغييرات مدة تصل إلى خمس دقائق.

الخطأ 404: Firebase AI Logic genai config not found

إذا تلقّيت الخطأ 404 الذي يشير إلى Firebase AI Logic genai config not found، يعني ذلك عادةً أنّ أحد إعدادات Firebase AI Logic غير مضبوط بشكل صحيح أو ناقص.

في ما يلي الأسباب الأكثر احتمالاً لحدوث هذا الخطأ:

• لم يتم إعداد مشروعك على Firebase لمقدّم خدمة Gemini API بعد.

  الإجراءات التي يجب اتّخاذها:
  في Firebase، انتقِل إلى خدمات الذكاء الاصطناعي > منطق الذكاء الاصطناعي. انقر على البدء، ثم اختَر مقدّم خدمة Gemini API الذي اخترته. فعِّل واجهة برمجة التطبيقات، وسيعمل Firebase على إعداد مشروعك لموفّر الخدمة هذا. بعد إكمال سير العمل، أعِد محاولة تنفيذ طلبك.

• إذا أكملت مؤخرًا سير عمل إعداد Firebase AI Logic في وحدة تحكّم Firebase، قد لا يكون إعداد Firebase AI Logic متاحًا بعد لجميع خدمات الخلفية المطلوبة في جميع المناطق السارية.

  ما عليك فعله:
  يُرجى الانتظار بضع دقائق، ثم إعادة محاولة تنفيذ طلبك.

الخطأ 404: النموذج "was not found or your project does not have access to it"؟

مثال: "Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."

هناك سببان مختلفان قد يؤديان إلى ظهور خطأ من هذا النوع.

• اسم الطراز غير صالح

  • السبب: اسم الطراز الذي قدّمته ليس اسم طراز صالحًا.

  • الحلّ: تحقَّق من اسم الطراز وإصداره مقارنةً بقائمة جميع الطرازات المتوافقة والمتوفّرة. احرص على التحقّق من الأقسام وترتيبها في اسم النموذج. على سبيل المثال:

    • اسم أحدث نموذج Gemini 3.x Pro: gemini-3.1-pro-preview (متاح في الإصدار التجريبي فقط)
    • أحدث Gemini 3.x Flash اسم طراز: gemini-3.8-flash
    • أحدث Gemini 3.x Flash‑Lite اسم طراز: gemini-3.5-flash-lite
    • اسم أحدث نموذج Gemini 3.x Pro Image (المعروف أيضًا باسم "Nano Banana Pro"): gemini-3-pro-image
    • اسم أحدث نموذج Gemini 3.x Flash Image (المعروف أيضًا باسم "Nano Banana 2"): gemini-3.1-flash-image
    • اسم أحدث نموذج Gemini 3.x Flash‑Lite Image (المعروف أيضًا باسم "Nano Banana 2 Lite"): gemini-3.1-flash-lite-image
    • اسم أحدث نموذج Gemini 2.5 Flash Image (المعروف أيضًا باسم "Nano Banana"): gemini-2.5-flash-image

• الموقع الجغرافي غير صالح (ينطبق ذلك فقط في حال استخدام مقدّم خدمة Agent Platform Gemini API (formerly Vertex AI))

  • السبب: قد يحاول طلبك الوصول إلى نموذج غير متوفّر في الموقع الجغرافي الذي اخترته.

  • الحلّ: تأكَّد من أنّ طلبك يحاول الوصول إلى النموذج الذي يتوفّر فيه.

    عند استخدام Agent Platform Gemini API (formerly Vertex AI)، يمكنك اختياريًا تحديد موقع جغرافي للوصول إلى النموذج أثناء عملية التهيئة. إذا لم تحدّد موقعًا جغرافيًا، سيتم تلقائيًا ضبط Firebase AI Logic على المواقع الجغرافية التالية:

    • عند استخدام بنية تهيئة "منصة الوكيل": global
    • عند استخدام بنية الإعداد القديمة "Vertex AI": us-central1

    ومع ذلك، لا تتوفّر بعض النماذج في هذه المواقع الجغرافية التلقائية. وهذا يعني أنّه قد يكون من الضروري تحديد موقع جغرافي معيّن بشكل واضح أثناء عملية الإعداد، وذلك حسب الطراز.

    • نماذج Gemini المعاينة والتجريبية: تتوفّر فقط في الموقع الجغرافي global.

    • نماذج Gemini 3.x الثابتة: متوفّرة في الموقع الجغرافي global وفي الموقعَين الجغرافيَين us وeu في كثير من الأحيان.

    • طُرز Gemini 2.5: تتوفّر في العديد من المواقع الجغرافية. يُرجى العِلم أنّ نماذج Gemini Live API 2.5 غير متاحة في global.

  مزيد من المعلومات حول كيفية تحديد الموقع الجغرافي الذي يمكن الوصول إلى النموذج منه (بما في ذلك مقتطفات الرموز)

أخطاء 429: "You exceeded your current quota, please check your plan and billing details" أو "Resource exhausted, please try again later."

هناك سببان مختلفان قد يؤديان إلى ظهور خطأ من هذا النوع.

• تجاوزت الحصة المخصّصة لك أو أنّ النموذج الذي تحاول الوصول إليه مثقل بالطلبات من مستخدمين آخرين.

  يعتمد الإجراء الذي يجب اتّخاذه على ما إذا كنت تستخدم Gemini Developer API أو Agent Platform Gemini API (formerly Vertex AI). لمزيد من المعلومات حول الحصص وطريقة طلب حصة إضافية، يُرجى الاطّلاع على حدود المعدّل والحصص.

  إذا كنت تستخدم Agent Platform Gemini API (formerly Vertex AI)، تقدّم مستندات Google Cloud بعض السياق والإرشادات الإضافية بشأن رمز الخطأ 429.

• تحاول استخدام نموذج أو ميزة تتطلّب الفوترة، ولكن مشروعك على Firebase يستخدِم خطة تسعير Spark.

  إذا كنت تستخدم Gemini Developer API، يمكنك الحصول على إذن وصول محدود إلى نماذج معيّنة وإلى العديد من الميزات الأساسية ضمن Gemini Developer API "الإصدار المجاني". تتيح لك هذه الفئة بدء الاستخدام بدون الحاجة إلى تقديم طريقة دفع، ما يعني أنّه ليس عليك ترقية مشروعك على Firebase إلى خطة أسعار "الفئة المَرِنة" بنظام الدفع حسب الاستخدام.

  • لا تتوفّر بعض النماذج في Gemini Developer API "المستوى المجاني" وتتطلّب "المستوى المدفوع"، ما يعني أنّ مشروعك يجب أن يكون ضمن خطة Blaze المَرِنة بنظام الدفع حسب الاستخدام. على سبيل المثال، تتطلّب النماذج التالية الفوترة دائمًا تقريبًا:

    • معظم النماذج التجريبية والتي تسبق الإصدار
    • نماذج إنشاء الصور (نماذج "Nano Banana")

  • تقدّم بعض النماذج بعض الميزات الأساسية ضمن Gemini Developer API "الخطة المجانية"، ولكنها تتطلّب الاشتراك في "الخطة المدفوعة" لاستخدام الميزات المتقدّمة. على سبيل المثال:

    • عند استخدام معظم نماذج Gemini 3.x، يتطلّب استخدام ميزة "الاستناد إلى مصادر" مع Google Search أو Google Maps دفع رسوم.

  مزيد من المعلومات حول خطط أسعار Firebase وGemini Developer API

  لمزيد من التفاصيل، يُرجى الاطّلاع على Gemini Developer API مستندات الأسعار والأسئلة الشائعة حول الفوترة.