رموز الخطأ

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

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

إليك الحلّ البديل لإصلاح مشروعك وتوفير وكلاء الخدمة هؤلاء بشكل صحيح حتى تتمكّن من تضمين عناوين 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: 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 API (firebasevertexai.googleapis.com) في قائمة واجهات برمجة التطبيقات المحدّدة التي يمكن طلب بياناتها باستخدام مفتاح واجهة برمجة التطبيقات.

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

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

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

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

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

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

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

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

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

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

إذا كنت تحاول استخدام Gemini Developer API وظهرت لك رسالة الخطأ 404 التي تفيد بأنّ Firebase AI Logic genai config not found، يعني ذلك عادةً أنّ مشروع Firebase لا يتضمّن مفتاح واجهة برمجة تطبيقات صالحًا Gemini لاستخدامه مع حِزم تطوير البرامج (SDK) الخاصة ببرنامج Firebase AI Logic.

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

• لم يتم إعداد مشروع Firebase الخاص بك من أجل Gemini Developer API بعد.

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

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

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

• ربما تم حذف مفتاح واجهة برمجة التطبيقات Gemini من مشروع Firebase.

  الإجراء المطلوب:
  تعرَّف على كيفية تغيير مفتاح واجهة برمجة التطبيقات Gemini المستخدَم من قِبل 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-pro-image-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."

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

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

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

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

    • اسم نموذج المعاينة Gemini 3.1 Pro هو gemini-3.1-pro-preview.
    • اسم نموذج المعاينة Gemini 3 Flash هو gemini-3-flash-preview.
    • اسم نموذج المعاينة "Nano Banana Pro" هو gemini-3-pro-image-preview.
    • اسم نموذج المعاينة "Nano Banana 2" هو gemini-3.1-flash-image-preview.
    • اسم نموذج "Nano Banana" هو gemini-2.5-flash-image.

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

  • السبب: أنت تستخدم إصدار معاينة أو إصدار تجريبي من نموذج (مثل gemini-3.1-pro-preview وgemini-3.1-flash-image-preview)، ولم تحدّد موقع global.

    في حال استخدامك Vertex AI Gemini API، لن تتوفّر جميع نماذج المعاينة والتجريبية Gemini (باستثناء نماذج Gemini Live) إلا في global. ومع ذلك، بما أنّ القيمة التلقائية Firebase AI Logic هي الموقع الجغرافي us-central1، عليك تحديد الموقع الجغرافي global بشكل صريح عند تهيئة خدمة الخلفية Vertex AI Gemini API في الرمز البرمجي عند استخدام نماذج Gemini المعاينة والتجريبية.

  • الحلّ: عند بدء خدمة Vertex AI Gemini API، حدِّد الموقع الجغرافي global. مزيد من المعلومات حول كيفية تحديد الموقع الجغرافي الذي يمكن الوصول إلى النموذج منه (بما في ذلك مقتطفات الرموز)

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

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

    إذا كنت تستخدم Vertex AI Gemini API، لا تتوفّر بعض النماذج إلا في مواقع جغرافية محدّدة. على سبيل المثال (وليس على سبيل الحصر):

    • طُرز Imagen غير متاحة في الموقع الجغرافي global.
    • تتوفّر نماذج Gemini Live API (مثل gemini-2.0-flash-live-preview-04-09) فقط في الموقع الجغرافي us-central1.
    • تتوفّر نماذج Gemini 2.5 (مثل gemini-2.5-pro) فقط في الموقع الجغرافي global والمواقع الجغرافية في الولايات المتحدة وبعض المواقع الجغرافية في أوروبا (وفي بعض الأحيان في مواقع جغرافية أخرى إذا كان مشروعك يتضمّن خيارات خاصة).

  • الحلّ: عند بدء خدمة Vertex AI Gemini API، احرص على تحديد موقع جغرافي متوافق مع النموذج الذي تستخدمه. مزيد من المعلومات حول كيفية تحديد الموقع الجغرافي الذي يمكن من خلاله الوصول إلى النموذج (بما في ذلك مقتطفات الرموز) والمواقع الجغرافية التي تتوفّر فيها النماذج

    يُرجى العِلم أنّ القيمة التلقائية لـ Firebase AI Logic هي الموقع الجغرافي us-central1.

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

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

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

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