בדף הזה מוסבר איך לפתור בעיות שקשורות לקודי שגיאה נפוצים ב-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 בבקשות המולטי-מודאליות, אתם יכולים להשתמש בפתרון העקיף הבא. אתם צריכים להיות הבעלים של הפרויקט, וצריך לבצע את קבוצת המשימות הזו רק פעם אחת בפרויקט.
לגשת אל gcloud CLI ולבצע אימות.
הדרך הכי קלה לעשות את זה היא דרך Cloud Shell. מידע נוסף זמין במאמרי העזרה בנושא Google Cloud.אם מופיעה בקשה, פועלים לפי ההוראות שמופיעות בטרמינל כדי להריץ את gcloud CLI בפרויקט ב-Firebase.
תצטרכו את מזהה הפרויקט ב-Firebase, שמופיע בחלק העליון של הגדרות הפרויקט במסוף Firebase. settings
מריצים את הפקודה הבאה כדי להקצות את סוכני השירות הנדרשים בפרויקט:
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 חוסמת את הגישה למודלים האלה, אלא אם הבקשות כוללות אסימון App Check תקין (לשם כך צריך לאכוף את App Check ב-Firebase AI Logic).
כדי לגשת למודל שהחזיר את השגיאה:
מגדירים את App Check עבור Firebase AI Logic. לפיתוח מקומי, חשוב להגדיר את App Check ספק האימות לצורכי ניפוי באגים.
אם כבר הגדרת את App Check, כדאי לוודא שביצעת את כל השלבים בהוראות שבקישור.
שולחים מחדש את הבקשה מהאפליקציה אל Firebase AI Logic.
הבקשה הזו תשלח אסימון App Check תקין, ולא תקבלו יותר את השגיאה 403.
עדיין מופיעה שגיאה 403?
אם המדיניות App Check נאכפת ושלחתם בקשה אבל אתם עדיין מקבלים את השגיאה 403, בדקו אם ההגנה מפני התקפות Replay נאכפת ב-Firebase AI Logic (כולל במצב "מעקב בלבד").
כשההגנה מפני התקפות Replay מופעלת, רק טוקנים לשימוש מוגבל נחשבים כמאומתים ב-Firebase AI Logic, כלומר טוקנים רגילים לסשן לא יכולים לפתור את שגיאת 403 הזו. כדי לפתור את הבעיה, צריך לבצע אחת מהפעולות הבאות:
אפשרות 1: אם אתם רוצים להשתמש בהגנה מפני מתקפות Replay, בדקו שוב את הגדרת ההגנה מפני מתקפות Replay.
חשוב לוודא שהשלמתם את כל השלבים של הגדרת ההגנה מפני התקפות Replay, כולל הפעלת טוקנים לשימוש מוגבל בבסיס הקוד של האפליקציה.
שליחת בקשה מחדש אל Firebase AI Logic.
אפשרות 2: אם אתם לא רוצים להשתמש בהגנה מפני התקפות Replay או שלא הפעלתם באפליקציה טוקנים לשימוש מוגבל, אתם יכולים לבטל את ההגנה מפני התקפות Replay.
מבטלים את אכיפת ההגנה מפני התקפות Replay במסוף Firebase: עוברים אל אבטחה > App Check > הכרטיסייה ממשקי API, לוחצים כדי להרחיב את השורה Firebase AI Logic, לוחצים על הגדרה ואז מבטלים את אכיפת ההגנה מפני התקפות Replay בתיבת הדו-שיח.
שליחת בקשה מחדש אל Firebase AI Logic.
לפני שמשיקים את האפליקציה למשתמשי קצה, צריך להגדיר ספק אימות בסביבת הייצור (כמו 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.
בלי App Check, הפרויקט שלכם חשוף לניצול לרעה של Gemini API. כדי להגן על הפרויקט, מערכת Firebase השביתה את השימוש ב-Firebase AI Logic עד שהבקשות יכללו אסימון App Check תקין (לשם כך צריך לאכוף את App Check ב-Firebase AI Logic).
כשתרצו להתחיל להשתמש שוב ב-Firebase AI Logic, בצעו את הפעולות הבאות:
מגדירים את App Check עבור Firebase AI Logic. לפיתוח מקומי, חשוב להגדיר את App Check ספק האימות לצורכי ניפוי באגים.
אם כבר הגדרת את App Check, כדאי לוודא שביצעת את כל השלבים בהוראות שבקישור.
שולחים מחדש את הבקשה מהאפליקציה אל Firebase AI Logic.
הבקשה הזו תשלח אסימון App Check תקין, ולא תקבלו יותר את השגיאה 403.
עדיין מופיעה שגיאה 403?
אם המדיניות App Check נאכפת ושלחתם בקשה אבל אתם עדיין מקבלים את השגיאה 403, בדקו אם ההגנה מפני התקפות Replay נאכפת ב-Firebase AI Logic (כולל במצב "מעקב בלבד").
כשההגנה מפני התקפות Replay מופעלת, רק טוקנים לשימוש מוגבל נחשבים כמאומתים ב-Firebase AI Logic, כלומר טוקנים רגילים לסשן לא יכולים לפתור את שגיאת 403 הזו. כדי לפתור את הבעיה, צריך לבצע אחת מהפעולות הבאות:
אפשרות 1: אם אתם רוצים להשתמש בהגנה מפני מתקפות Replay, בדקו שוב את הגדרת ההגנה מפני מתקפות Replay.
חשוב לוודא שהשלמתם את כל השלבים של הגדרת ההגנה מפני התקפות Replay, כולל הפעלת טוקנים לשימוש מוגבל בבסיס הקוד של האפליקציה.
שליחת בקשה מחדש אל Firebase AI Logic.
אפשרות 2: אם אתם לא רוצים להשתמש בהגנה מפני התקפות Replay או שלא הפעלתם באפליקציה טוקנים לשימוש מוגבל, אתם יכולים לבטל את ההגנה מפני התקפות Replay.
מבטלים את אכיפת ההגנה מפני התקפות Replay במסוף Firebase: עוברים אל אבטחה > App Check > הכרטיסייה ממשקי API, לוחצים כדי להרחיב את השורה Firebase AI Logic, לוחצים על הגדרה ואז מבטלים את אכיפת ההגנה מפני התקפות Replay בתיבת הדו-שיח.
שליחת בקשה מחדש אל Firebase AI Logic.
לפני שמשיקים את האפליקציה למשתמשי קצה, צריך להגדיר ספק אימות בסביבת הייצור (כמו 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.
כך עושים את זה:
במסוף Google Cloud, פותחים את החלונית APIs & Services > Credentials.
בוחרים את מפתח ה-API שהאפליקציה מוגדרת להשתמש בו (לדוגמה, "מפתח iOS" לאפליקציה ל-iOS).
בדף Edit API key, מאתרים את הקטע API restrictions.
מוודאים שהאפשרות Restrict key מסומנת. אם לא, המפתח לא מוגבל, וכנראה שזו לא הסיבה לשגיאה.
בתפריט הנפתח Selected APIs, מחפשים את Firebase AI Logic API ובוחרים בו כדי להוסיף אותו לרשימת ממשקי ה-API שנבחרו, שאפשר לקרוא להם באמצעות מפתח ה-API.
לוחצים על שמירה.
יכול להיות שיעברו עד חמש דקות עד שהשינויים ייכנסו לתוקף.
שגיאת 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 Hydrogen:
gemini-4-hydrogen - שם המודל העדכני של Gemini 4 Argon:
gemini-4-argon - שם המודל העדכני של Gemini 4 Carbon:
gemini-4-carbon - שם המודל העדכני של 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 Hydrogen:
מודל מושבת (שהופסק)
הסיבה: המודל שניסיתם לגשת אליו עבר את תאריך ההשבתה (הוצאה משימוש) שלו והושבת באופן סופי (לדוגמה, מודלים של 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)).
- כשמשתמשים בתחביר של 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 בתשלום לפי שימוש. לדוגמה, המודלים הבאים כמעט תמיד דורשים חיוב:
- רוב המודלים בגרסת טרום-השקה (Preview) והניסיוניים
- מודלים ליצירת מדיה (כמו המודלים של Gemini Nano Banana)
בחלק מהמודלים יש תכונות בסיסיות בחינם (Gemini Developer API), אבל כדי להשתמש בתכונות מתקדמות יותר צריך לשלם. לדוגמה:
- ברוב המודלים של Gemini 3.x, כדי להשתמש ב-Grounding עם
Google Search אוGoogle Maps צריך להגדיר חיוב.
- ברוב המודלים של Gemini 3.x, כדי להשתמש ב-Grounding עם
מידע על תוכניות התמחור והתשלומים של Firebase ועל Gemini Developer API.
פרטים נוספים זמינים בGemini Developer APIמסמכי התיעוד בנושא תמחור ובשאלות הנפוצות בנושא חיוב.