שגיאות 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.
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.

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