تقدّم هذه الصفحة معلومات حول تحديد وحلّ المشاكل المتعلقة برموز الأخطاء الشائعة في حزمتَي تطوير البرامج (SDK) لكل من Gemini API وFirebase AI Logic.
الخطأ 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 في طلباتك المتعددة الوسائط. يجب أن تكون مالكًا للمشروع، وعليك إكمال هذه المجموعة من المهام مرة واحدة فقط لمشروعك.
الوصول إلى gcloud CLI والمصادقة عليه
أسهل طريقة لإجراء ذلك هي من خلال Cloud Shell. يمكنك الاطّلاع على مزيد من المعلومات في مستندات Google Cloud.اتّبِع التعليمات التي تظهر في الوحدة الطرفية إذا طُلب منك ذلك لتشغيل gcloud CLI في مشروع Firebase.
ستحتاج إلى رقم تعريف مشروعك على Firebase، والذي يمكنك العثور عليه في أعلى صفحة settings إعدادات المشروع في وحدة تحكّم Firebase.
يمكنك توفير وكلاء الخدمة المطلوبين في مشروعك من خلال تنفيذ الأمر التالي:
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 ''
يُرجى الانتظار بضع دقائق للتأكّد من توفير وكلاء الخدمة، ثم إعادة محاولة إرسال طلبك المتعدّد الوسائط الذي يتضمّن عنوان 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).
إذا أردت الوصول إلى النموذج الذي عرض الخطأ، اتّبِع الخطوات التالية:
إعداد App Check لـ "Firebase AI Logic" للتطوير على الجهاز، تأكَّد من إعداد App Check مقدّم خدمة تصحيح الأخطاء.
يُعدّ فرض App Check أمرًا بالغ الأهمية للمساعدة في حماية نماذج Gemini API وGemini من إساءة الاستخدام، ويجب فرضها لإزالة هذا الخطأ.
أعِد إرسال الطلب من تطبيقك إلى Firebase AI Logic.
سيرسل هذا الطلب رمزًا مميزًا صالحًا لـ App Check، ولن يظهر لك خطأ
403 - PERMISSION_DENIEDبعد ذلك.قبل طرح تطبيقك للمستخدمين النهائيين، عليك إعداد مقدّم خدمة مصادقة الإصدار العلني (مثل 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 مرة أخرى، اتّبِع الخطوات التالية:
إعداد App Check لـ "Firebase AI Logic" للتطوير على الجهاز، تأكَّد من إعداد App Check مقدّم خدمة تصحيح الأخطاء.
يُعدّ فرض App Check أمرًا بالغ الأهمية للمساعدة في حماية نماذج Gemini API وGemini من إساءة الاستخدام، ويجب فرضها لإزالة هذا الخطأ.
أعِد إرسال الطلب من تطبيقك إلى Firebase AI Logic.
سيرسل هذا الطلب رمزًا مميزًا صالحًا لـ App Check، ولن يظهر لك خطأ
403 - PERMISSION_DENIEDبعد ذلك.إذا كنت تفرض استخدام App Check ولا يزال هذا الخطأ يظهر لك، يُرجى التحقّق مما إذا كانت ميزة الحماية من إعادة التشغيل مفعَّلة في Firebase AI Logic (بما في ذلك في وضع "المراقبة فقط").
عند تفعيل ميزة "الحماية من إعادة التشغيل"، يتم احتساب الرموز المميّزة المحدودة الاستخدام فقط على أنّها تم التحقّق منها لـ "Firebase AI Logic"، ولا تؤدي الرموز المميّزة للجلسات العادية إلى إزالة هذا الخطأ. يمكنك إما تفعيل الرموز المميّزة المحدودة الاستخدام في تطبيقك، أو إيقاف ميزة "الحماية من إعادة التشغيل" لواجهة برمجة التطبيقات Firebase AI Logic، وإعادة إرسال الطلب، والانتظار لمدة يوم تقريبًا قبل إعادة تفعيل ميزة "الحماية من إعادة التشغيل" (تتم إعادة تقييم نشاط المشروع يوميًا).
قبل طرح تطبيقك للمستخدمين النهائيين، عليك إعداد مقدّم خدمة مصادقة الإصدار العلني (مثل 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
مختلف.
تحقَّق من أنّ مفتاح واجهة برمجة التطبيقات المُدرَج في ملف إعدادات 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" لتضمين واجهة برمجة التطبيقات المطلوبة. بالنسبة إلى Firebase AI Logic،
عليك التأكّد من أنّ واجهة برمجة تطبيقات Firebase AI Logic
(firebasevertexai.googleapis.com) مضمّنة في قائمة واجهات برمجة التطبيقات
المحدّدة التي يمكن طلبها باستخدام مفتاح واجهة برمجة التطبيقات.
اتبع هذه الخطوات:
في وحدة تحكّم Google Cloud، افتح لوحة واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.
اختَر مفتاح واجهة برمجة التطبيقات الذي تم ضبط تطبيقك لاستخدامه (على سبيل المثال، "مفتاح iOS" لتطبيق iOS).
في صفحة تعديل مفتاح واجهة برمجة التطبيقات، ابحث عن قسم قيود واجهة برمجة التطبيقات.
تأكَّد من تحديد الخيار تقييد المفتاح. إذا لم يكن الأمر كذلك، فهذا يعني أنّ مفتاحك غير مقيّد، ومن المرجّح أنّه ليس مصدر الخطأ.
في القائمة المنسدلة واجهات برمجة التطبيقات المحدّدة، ابحث عن واجهة برمجة التطبيقات Firebase AI Logic واختَرها لإضافتها إلى قائمة واجهات برمجة التطبيقات المحدّدة التي يمكن طلبها باستخدام مفتاح واجهة برمجة التطبيقات.
انقر على حفظ.
قد يستغرق تطبيق التغييرات مدة تصل إلى خمس دقائق.
خطأ 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: النموذج "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 4 Argon:
gemini-4-argon - اسم أحدث طراز من Gemini 3.x Flash:
gemini-3.8-flash - اسم أحدث طراز من Gemini 3.x Flash‑Lite:
gemini-3.5-flash-lite - اسم أحدث طراز من Gemini Nano Banana 2.1:
gemini-nano-banana-2.1 - اسم أحدث طراز من Gemini Nano Banana 2:
gemini-3.1-flash-image - اسم أحدث طراز من Gemini Nano Banana 2 Lite:
gemini-3.1-flash-lite-image - اسم أحدث طراز من Gemini Nano Banana Pro:
gemini-3-pro-image
- اسم أحدث طراز من Gemini 4 Argon:
النموذج المتوقف نهائيًا (المتقاعد)
السبب: تجاوز النموذج الذي تحاول الوصول إليه تاريخ إيقافه (إيقافه نهائيًا) وتم إيقافه نهائيًا (على سبيل المثال، نماذج Gemini 2.5 للاستخدام العام على Agent Platform Gemini API (formerly Vertex AI)، أو نماذج Gemini 2.0، أو نماذج Imagen).
الحلّ: يُرجى الاطّلاع على الأسئلة الشائعة حول النماذج المتوقفة نهائيًا وتعديل الرمز لاستخدام نموذج بديل نشط.
الموقع الجغرافي غير صالح (ينطبق فقط في حال استخدام مقدّم الخدمة 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.النموذجان الثابتان Gemini 4.x وGemini 3.x: يتوفّران في الموقع الجغرافي
globalوغالبًا في الموقعَين الجغرافيَينusوeu.نماذج Gemini Live API 2.5: تتوفّر في العديد من المواقع الجغرافية، ولكنّها غير متوفّرة في
global. (يُرجى العِلم أنّه تم إيقاف نماذج Gemini 2.5 ذات الاستخدام العام في Agent Platform Gemini API (formerly Vertex AI).)
- عند استخدام بنية الإعداد "Agent Platform":
مزيد من المعلومات حول كيفية تحديد الموقع الجغرافي للوصول إلى النموذج (بما في ذلك مقتطفات الرموز)
أخطاء 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 المَرِنة. على سبيل المثال، تتطلّب النماذج التالية دائمًا تقريبًا الفوترة:
- معظم النماذج التجريبية والحصرية
- النماذج التي تنشئ الوسائط (مثل نماذج Gemini Nano Banana)
توفّر بعض النماذج بعض الميزات الأساسية في Gemini Developer API "الفئة المجانية"، ولكنّها تتطلّب بعد ذلك "الفئة المدفوعة" لاستخدام الميزات المتقدّمة. على سبيل المثال:
- عند استخدام معظم نماذج Gemini 3.x،
تتطلّب ميزة "التحقّق من المصادر باستخدام
Google Search " أو "Google Maps " تفعيل الفوترة.
- عند استخدام معظم نماذج Gemini 3.x،
تتطلّب ميزة "التحقّق من المصادر باستخدام
مزيد من المعلومات حول خطط أسعار Firebase وGemini Developer API
لمزيد من التفاصيل، يُرجى الاطّلاع على Gemini Developer API مستندات الأسعار و الأسئلة الشائعة حول الفوترة.