קודי שגיאה

בדף הזה מוסבר איך לפתור בעיות שקשורות לקודי שגיאה נפוצים ב-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, שמופיע בחלק העליון של הגדרות הפרויקט במסוף 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 (כולל במצב "מעקב בלבד").

   כשההגנה מפני התקפות חזרה מופעלת, רק טוקנים לשימוש מוגבל נחשבים כמאומתים ב-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 Pro: gemini-3.1-pro-preview (זמין רק בגרסת טרום-השקה (Preview))
    • שם המודל העדכני של 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

• מיקום לא תקין (רלוונטי רק אם משתמשים בספק 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 2.5: זמינים בהרבה מיקומים. שימו לב שהמודלים של Gemini Live API 2.5 לא זמינים ב-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 בתשלום לפי שימוש. לדוגמה, המודלים הבאים כמעט תמיד דורשים חיוב:

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

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

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

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

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