رموز الخطأ

الخطأ 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 Console.

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

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

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

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

إليك الحلّ البديل لإصلاح مشروعك وتوفير وكلاء الخدمة هؤلاء بشكلٍ صحيح حتى تتمكّن من البدء في تضمين عناوين 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. انتظِر بضع دقائق للتأكّد من توفير وكلاء الخدمة، و ثم أعِد محاولة إرسال طلبك المتعدد الوسائط الذي يتضمّن Cloud Storage for Firebase عنوان URL.

إذا استمر ظهور هذا الخطأ بعد الانتظار لعدة دقائق، تواصَل مع فريق دعم 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 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 Console.

إذا تبيّن لك أنّهما لا يتطابقان، ثم احصل على ملف إعداد 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 لتضمين واجهة برمجة التطبيقات المطلوبة. بالنسبة إلى Firebase AI Logic، عليك التأكّد من أنّ Firebase AI Logic واجهة برمجة التطبيقات (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، انتقِل إلى خدمات الذكاء الاصطناعي > AI Logic. انقر على البدء، ثم اختَر مزوّد Gemini API الذي تريده. فعِّل واجهة برمجة التطبيقات، وسيضبط Firebase مشروعك لهذا المزوّد. بعد إكمال سير العمل، أعِد محاولة إرسال طلبك.

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

  الإجراء المطلوب:
  انتظِر بضع دقائق، ثم أعِد محاولة إرسال طلبك.

الخطأ 404: the model "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.7-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 المواقع الجغرافية التالية تلقائيًا:

    • عند استخدام صيغة الإعداد "Agent Platform": ‏global
    • عند استخدام صيغة الإعداد القديمة "Vertex AI": ‏us-central1

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

    • Gemini نماذج المعاينة و التجريبية: لا تتوفّر إلا في الموقع الجغرافي global (باستثناء نماذج Live API - اطّلِع أدناه).

    • Gemini 3.x نماذج: لا تتوفّر إلا في الموقع الجغرافي global عند استخدام Firebase AI Logic. Firebase AI Logic لا يتوافق بعد مع الموقعَين الجغرافيَين us وeu.

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

    • Gemini Live API نماذج: لا تتوفّر إلا في الموقع الجغرافي us-central1. الموقع الجغرافي 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 إلى خطة تسعير Blaze بنظام الدفع حسب الاستخدام.

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

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

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

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

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

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