קודי שגיאה

בדף הזה מוסבר איך לפתור בעיות שקשורות לקודי שגיאה נפוצים ב-SDK של Gemini API וב-SDK של 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., בדרך כלל המשמעות היא שמפתח ה-API בקובץ התצורה או באובייקט של הגדרות Firebase לא קיים, או שהוא לא מוגדר לשימוש עם האפליקציה או עם הפרויקט ב-Firebase.

בודקים שמפתח ה-API שרשום בקובץ התצורה או באובייקט של הגדרות Firebase תואם למפתח ה-API של האפליקציה. אפשר לראות את כל מפתחות ה-API בחלונית APIs & Services > Credentials במסוף Google Cloud.

אם אין התאמה, צריך להשיג קובץ או אובייקט חדש של הגדרות אישיות ב-Firebase, ואז להחליף את הקובץ או האובייקט שבאפליקציה. הקובץ או האובייקט החדש של ההגדרות האישיות צריך להכיל מפתח API תקין לאפליקציה ולפרויקט ב-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.

השגיאה הזו נגרמת בגלל פרויקט שסוכני השירות הנדרשים לא הוקצו לו באופן אוטומטי בצורה נכונה כשה-API של Agent Platform הופעל בפרויקט. זו בעיה מוכרת בחלק מהפרויקטים, ואנחנו עובדים על תיקון גלובלי.

כדי לתקן את הפרויקט ולהקצות בצורה נכונה את סוכני השירות האלה, כך שתוכלו להתחיל לכלול כתובות URL של Cloud Storage for Firebase בבקשות המולטי-מודאליות, אתם יכולים להשתמש בפתרון העקיף הבא. אתם צריכים להיות הבעלים של הפרויקט, וצריך לבצע את קבוצת המשימות הזו רק פעם אחת בפרויקט.

1. גישה ואימות באמצעות gcloud CLI.
   הדרך הכי קלה לעשות את זה היא דרך Cloud Shell. מידע נוסף זמין במאמרי העזרה בנושא Google Cloud.

2. אם מופיעה בקשה, פועלים לפי ההוראות שמופיעות במסוף כדי להריץ את gcloud CLI בפרויקט ב-Firebase.

   תצטרכו את מזהה הפרויקט ב-Firebase, שמופיע בחלק העליון של הדף Project 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).

אזהרה: החל מ-2 בנובמבר 2026, Firebase 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) כדי שמשתמשי הקצה יוכלו לגשת לתכונת ה-AI כשאוכפים את 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.

אזהרה: החל מ-2 בנובמבר 2026, Firebase 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 (כולל במצב "מעקב בלבד").

   כשההגנה מפני התקפות Replay מופעלת, רק טוקנים לשימוש מוגבל נחשבים כמאומתים ב-Firebase AI Logic. טוקנים רגילים לסשן לא פותרים את השגיאה הזו. צריך להפעיל באפליקציה טוקנים לשימוש מוגבל או להשבית את ההגנה מפני התקפות Replay ב-Firebase AI Logic, לשלוח מחדש בקשה ולהמתין כיום לפני שמפעילים שוב את ההגנה מפני התקפות Replay (הפעילות בפרויקט נבדקת מחדש מדי יום).

4. לפני שמשיקים את האפליקציה למשתמשי הקצה, צריך להגדיר ספק אימות בסביבת הייצור (כמו App Attest,‏ Play Integrity או reCAPTCHA Enterprise) כדי שמשתמשי הקצה יוכלו לגשת לתכונת ה-AI כשאוכפים את App Check.

שגיאה 403: PERMISSION_DENIED: The caller does not have permission.

אם מופיעה שגיאה 403 עם ההודעה PERMISSION_DENIED: The caller does not have permission., בדרך כלל המשמעות היא שמפתח ה-API בקובץ או באובייקט של הגדרות Firebase שייך לפרויקט אחר ב-Firebase.

בודקים שמפתח ה-API שרשום בקובץ התצורה או באובייקט של הגדרות Firebase תואם למפתח ה-API של האפליקציה. אפשר לראות את כל מפתחות ה-API בחלונית APIs & Services > Credentials במסוף Google Cloud.

אם אין התאמה, צריך להשיג קובץ או אובייקט חדש של הגדרות אישיות ב-Firebase, ואז להחליף את הקובץ או האובייקט שבאפליקציה. הקובץ או האובייקט החדש של ההגדרות האישיות צריך להכיל מפתח API תקין לאפליקציה ולפרויקט ב-Firebase.

שגיאה 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.

אם אתם מקבלים את השגיאה 403 עם ההודעה Requests to this API firebasevertexai.googleapis.com ... are blocked., בדרך כלל זה אומר שיש הגבלות על מפתח ה-API בהגדרות של Firebase באפליקציה, שמונעות ממנו לשלוח קריאה ל-API הנדרש.

כדי לפתור את הבעיה, צריך לעדכן את ההגבלות על מפתח ה-API במסוף Google Cloud כך שיכללו את ה-API הנדרש. ב-Firebase AI Logic, צריך לוודא ש-Firebase AI Logic API (firebasevertexai.googleapis.com) נכלל ברשימת ממשקי ה-API שנבחרו, שאפשר לשלוח אליהם קריאה באמצעות מפתח ה-API.

כך עושים את זה:

1. במסוף Google Cloud, פותחים את החלונית APIs & Services > Credentials.

2. בוחרים את מפתח ה-API שהאפליקציה מוגדרת להשתמש בו (לדוגמה, "מפתח iOS" לאפליקציה ל-iOS).

3. בדף עריכת מפתח API, מאתרים את הקטע הגבלות API.

4. מוודאים שהאפשרות Restrict key מסומנת. אם לא, המפתח לא מוגבל, וכנראה שזו לא הסיבה לשגיאה.

   הערה: אם יש לכם מפתח API ללא הגבלה, מומלץ מאוד להחיל הגבלות על ממשקי API במפתח ה-API של Firebase.

5. בתפריט הנפתח Selected APIs, מחפשים את Firebase AI Logic API ובוחרים בו כדי להוסיף אותו לרשימת ממשקי ה-API שנבחרו, שאפשר לקרוא להם באמצעות מפתח ה-API.

6. לוחצים על שמירה.

   יכול להיות שיעברו עד חמש דקות עד שהשינויים ייכנסו לתוקף.

הערה: ממשקי API שקשורים ל-Firebase משתמשים במפתחות API רק כדי לזהות את הפרויקט או האפליקציה ב-Firebase, ולא כדי לאשר קריאה ל-API (כמו שממשקי API אחרים מאפשרים). ההרשאה לממשקי API שקשורים ל-Firebase מטופלת בנפרד ממפתח ה-API, באמצעות הרשאות IAM של Google Cloud, ‏Firebase Security Rules או Firebase App Check. מידע נוסף על מפתחות API של Firebase

שגיאת 404: Firebase AI Logic genai config not found

אם מופיעה שגיאה 404 עם ההודעה Firebase AI Logic genai config not found, בדרך כלל זה אומר שאחת מההגדרות של Firebase AI Logic לא נכונה או חסרה.

אלה הסיבות הסבירות ביותר לשגיאה הזו:

• עדיין לא הגדרת את פרויקט Firebase לספק Gemini API.

  מה צריך לעשות:
  במסוף Firebase, נכנסים ל-AI Services ‏> AI Logic. לוחצים על תחילת העבודה ובוחרים את ספק ה-Gemini API הרצוי. מפעילים את ה-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 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 גרסת טרום-השקה (Preview) ומודלים ניסיוניים: זמינים רק במיקום 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)).

  איך מציינים את המיקום לגישה למודל (כולל קטעי קוד).

שגיאות 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 בתשלום לפי שימוש. לדוגמה, המודלים הבאים כמעט תמיד דורשים חיוב:

    • רוב המודלים בגרסת טרום-השקה (Preview) והניסיוניים
    • מודלים ליצירת מדיה (כמו המודלים של Gemini Nano Banana)

  • חלק מהמודלים מציעים תכונות בסיסיות בGemini Developer API "תוכנית בחינם", אבל כדי להשתמש בתכונות מתקדמות יותר צריך לעבור ל "תוכנית בתשלום". לדוגמה:

    • ברוב המודלים של Gemini 3.x, כדי להשתמש ב-Grounding עם Google Search או Google Maps צריך להגדיר חיוב.

  מידע על תוכניות התמחור והתשלומים של Firebase ועל Gemini Developer API

  פרטים נוספים זמינים בGemini Developer APIמסמכי התיעוד בנושא תמחור ובשאלות הנפוצות בנושא חיוב.