שגיאות API

בדף הזה מפורטים קודי השגיאה של הבק-אנד שמוחזרים על ידי GenerateContent API, מוסבר פורמט התגובה של שגיאת gRPC ומפורטים שלבים לפתרון בעיות.

קודי שגיאה של HTTP

בטבלה הבאה מפורטים קודי שגיאה נפוצים של ה-Backend, הסברים לגבי הסיבות לשגיאות ופתרונות מומלצים:

קוד HTTP סטטוס תיאור דוגמה המוצר
400 INVALID_ARGUMENT גוף הבקשה לא תקין. יש שגיאת הקלדה או שחסר שדה חובה בבקשה. במאמרי העזרה של ה-API אפשר למצוא מידע על פורמט הבקשות, דוגמאות וגרסאות נתמכות. שימוש בתכונות מגרסת API חדשה יותר עם נקודת קצה ישנה יותר עלול לגרום לשגיאות.
400 FAILED_PRECONDITION השימוש ב-Gemini API בחינם לא זמין במדינה שלך. צריך להפעיל את החיוב בפרויקט ב-Google AI Studio. אתם שולחים בקשה באזור שבו התוכנית החינמית לא אפשרית, ולא הפעלתם חיוב בפרויקט שלכם ב-Google AI Studio. כדי להשתמש ב-Gemini API, תצטרכו להגדיר תוכנית בתשלום באמצעות Google AI Studio.
402 RESOURCE_EXHAUSTED יתרת הזיכוי בתשלום מראש אזלה. הקרדיטים בתשלום מראש בחשבון לחיוב שלכם אזלו, ולכן כל מפתחות ה-API שמקושרים לחשבון הזה מפסיקים לפעול. מוסיפים קרדיטים לחשבון לחיוב או מפעילים את התכונה הוספת כסף אוטומטית. אל תנסו לשלוח את הבקשה הזו שוב: היא לא תאושר עד שיוספו קרדיטים.
403 PERMISSION_DENIED למפתח ה-API שלכם אין את ההרשאות הנדרשות. אתם משתמשים במפתח API שגוי. אתם מנסים להשתמש במודל שעבר התאמה בלי לעבור אימות תקין. בודקים שמפתח ה-API מוגדר ושיש לו את הגישה הנכונה. כדי להשתמש במודלים שעברו התאמה, חשוב לוודא שאתם עוברים אימות תקין.
404 NOT_FOUND המשאב המבוקש לא נמצא. לא נמצא קובץ תמונה, אודיו או וידאו שהייתה אליו הפניה בבקשה שלך. בודקים אם כל הפרמטרים בבקשה תקפים לגרסת ה-API שלכם.
429 RESOURCE_EXHAUSTED חרגתם מאחת ממגבלות הקצב של ה-API (RPM,‏ TPM,‏ RPD, הוצאות וכו'). אתם שולחים יותר מדי בקשות, משתמשים ביותר מדי טוקנים או חורגים ממגבלות שמבוססות על הוצאות בהיסטוריית החיובים ובתוכנית של החשבון. מוודאים שאתם עומדים במגבלות הקצב של המודל. מחכים קצת ומנסים שוב. צריך להקטין את קצב הבקשות או את הגודל שלהן. במקרה הצורך, מבקשים להגדיל את מגבלת קצב הבקשות.
499 בוטלה הפעולה בוטלה, בדרך כלל על ידי המתקשר. הלקוח סגר את החיבור לפני שה-API סיים להגיב. בודקים אם תשתית הלקוח או הרשת סוגרת את החיבור לפני הזמן (למשל, בגלל פסק זמן בצד הלקוח).
500 פנימי קרתה שגיאה לא צפויה בצד של Google. הקשר של הקלט ארוך מדי. כדאי לבדוק את דף הסטטוס של Gemini API כדי לראות אם יש תקריות שמתרחשות כרגע. כדאי לצמצם את הקשר של הקלט או לעבור באופן זמני למודל אחר (למשל מ-Gemini 2.5 Pro ל-Gemini 2.5 Flash) ולבדוק אם זה עוזר. אפשר גם להמתין קצת ולנסות שוב לשלוח את הבקשה. אם הבעיה נמשכת אחרי שמנסים שוב, אפשר לדווח עליה באמצעות הכפתור שליחת משוב ב-Google AI Studio.
503 UNAVAILABLE יכול להיות שהשירות עמוס מדי או מושבת באופן זמני. השירות לא זמין כרגע בגלל עומס. כדאי לבדוק את דף הסטטוס של Gemini API כדי לראות אם יש תקריות שמתרחשות כרגע. עוברים באופן זמני למודל אחר (למשל מ-Gemini 2.5 Pro ל-Gemini 2.5 Flash) ובודקים אם זה עובד. אפשר גם להמתין קצת ולנסות שוב לשלוח את הבקשה. אם הבעיה נמשכת אחרי שמנסים שוב, אפשר לדווח עליה באמצעות הכפתור שליחת משוב ב-Google AI Studio.
504 DEADLINE_EXCEEDED השירות לא יכול לסיים את העיבוד עד למועד האחרון. ההנחיה (או ההקשר) גדולה מדי ואי אפשר לעבד אותה בזמן. כדי למנוע את השגיאה הזו, צריך להגדיר ערך גבוה יותר של 'פסק זמן' בבקשת הלקוח.

פורמט של תגובת שגיאה

כשבקשת GenerateContent נכשלת, ה-API מגדיר את קוד הסטטוס של HTTP (למשל 400 Bad Request, 403 Forbidden או 429 Too Many Requests) ומחזיר גוף תגובה בפורמט JSON שמכיל פרטי סטטוס של gRPC:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
שדה סוג תיאור
code מספר שלם קוד הסטטוס של HTTP.
message מחרוזת תיאור השגיאה שכתוב בצורה שקריאה לאנשים.
status מחרוזת קוד הסטטוס של gRPC ב-SCREAMING_CASE.
details מערך הקשר נוסף של השגיאה, כמו ErrorInfo או LocalizedMessage.

המאמרים הבאים