رموز الخطأ

تقدّم هذه الصفحة معلومات لتحديد المشاكل وحلّها في ما يتعلّق برموز الأخطاء الشائعة لـ Gemini API وFirebase AI Logic حِزم تطوير البرامج (SDK).

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

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

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

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

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

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

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: 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. تأكَّد من اختيار الخيار فرض قيود على المفتاح. إذا لم يكن هذا الخيار محدّدًا، يعني ذلك أنّ مفتاحك غير مقيّد، ومن المحتمل ألا يكون هذا هو مصدر الخطأ.

   ملاحظة: إذا كان لديك مفتاح واجهة برمجة تطبيقات غير مقيّد، ننصحك بشدة بـ فرض "قيود على واجهة برمجة التطبيقات" على مفتاح واجهة برمجة تطبيقات Firebase.

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

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

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

ملاحظة: لا تستخدم واجهات برمجة التطبيقات ذات الصلة بمنصة Firebase مفاتيح واجهة برمجة التطبيقات إلا لتحديد مشروع Firebase أو التطبيق، وليس للحصول على إذن استدعاء واجهة برمجة التطبيقات (كما تسمح بعض واجهات برمجة التطبيقات الأخرى). تتم معالجة إذن واجهات برمجة التطبيقات ذات الصلة بمنصة Firebase بشكلٍ منفصل عن مفتاح واجهة برمجة التطبيقات، إما من خلال أذونات Google Cloud "إدارة الهوية وإمكانية الوصول"، Firebase Security Rules، أو Firebase App Check. مزيد من المعلومات عن مفاتيح واجهة برمجة تطبيقات Firebase.

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

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

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

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

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

  الإجراء المطلوب:
  تعرَّف على كيفية تغيير مفتاح واجهة برمجة التطبيقات Gemini الذي يستخدمه 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.5-flash
    • اسم أحدث نموذج Gemini 3.x Flash‑Lite‏: gemini-3.1-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

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

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

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

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

    • Gemini نماذج التجريبية و الخاضعة للتجربة: يجب ضبط الموقع الجغرافي على global (باستثناء Live API). لا تتوفّر جميع نماذج التجريبية و الخاضعة للتجربة Gemini (باستثناء نماذج Live API ) إلا في الموقع الجغرافي global.

    • Gemini 3.x نماذج: يجب ضبط الموقع الجغرافي على global عند استخدام Firebase AI Logic. لا يتيح Firebase AI Logic بعد المواقع الجغرافية us وeu.

    • Gemini 2.5 نماذج: ضبط الموقع الجغرافي اختياري. إذا لم تحدّد موقعًا جغرافيًا، يكون الموقع الجغرافي التلقائي هو us-central1.

    • 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."

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

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

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