שגיאות API

בדף הזה מפורטים כל קודי השגיאה של Interactions API, מתואר הפורמט של תגובת השגיאה ומוסבר איך ה-API מחזיר שגיאות לסוגי בקשות שונים.

קודי שגיאה ב-Standard API

קודי השגיאה הכלליים האלה ברמת הבקשה תואמים לקודי סטטוס של HTTP. כדי לטפל בשגיאות באופן פרוגרמטי, משתמשים בשדה code בלוגיקה של האפליקציה.

קוד סטטוס HTTP תיאור הפעולה המומלצת
invalid_request ‫400 בקשה לא תקינה המטען הייעודי (payload) של הבקשה לא תקין או מכיל פרמטרים לא חוקיים. צריך לבדוק את התחביר והפרמטרים של הבקשה בהתאם למאמרי העזרה של ה-API.
failed_precondition ‫400 בקשה לא תקינה אי אפשר לעבד את הבקשה כי לא התקיים תנאי מוקדם (לדוגמה, החיוב מושבת). אימות סטטוס החיוב של הפרויקט או הדרישות המוקדמות של החשבון.
out_of_range ‫416 Requested Range Not Satisfiable (לא ניתן לספק את הטווח המבוקש) פרמטר הבקשה מחוץ לטווח החוקי. בודקים את ערכי הפרמטרים והמגבלות.
parameter_unknown ‫400 בקשה לא תקינה הבקשה מכילה פרמטר לא ידוע. מסירים את הפרמטר הלא מזוהה ומנסים שוב.
authentication ‫401 אין הרשאה מפתח ה-API חסר, לא תקין או שפג תוקפו. מאמתים את מפתח ה-API.
payment_required ‫402 נדרש תשלום יתרת הזכות מהתשלום מראש נוצלה במלואה. מוסיפים קרדיטים לחשבון לחיוב או מפעילים את התכונה הוספת כסף אוטומטית. אל תנסו שוב: הבקשה לא תצליח עד שיתווספו קרדיטים.
permission_denied ‫403 אסור למפתח ה-API שלכם אין הרשאה למשאב הזה, או שהגישה של הפרויקט ל-API מוגבלת. בודקים את ההרשאות של מפתח ה-API, את הזכאות לרמת הפרויקט ואת סטטוס החיוב. פתרון בעיות שקשורות לפרויקט מוגבל או לא זמין
not_found שגיאת 404 המשאב המבוקש לא נמצא. מאמתים את הנתיב והפרמטרים של המשאב.
model_not_found שגיאת 404 המודל שצוין לא נמצא. צריך לוודא ששם המודל נכון או להשתמש במודל אחר.
already_exists ‫409 התנגשות הישות שניסית ליצור כבר קיימת. לפני שיוצרים מחדש את המשאב, בודקים אם הוא כבר קיים.
aborted ‫409 התנגשות הפעולה בוטלה בגלל התנגשות או כשל בבדיקת בו-זמניות. נסו לשלוח שוב את הבקשה ברמת אפליקציה גבוהה יותר.
rate_limit_exceeded ‫429 יותר מדי בקשות חרגתם ממגבלת הבקשות או הטוקנים לדקה או לשנייה. צריך להמתין ולנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
quota_exceeded ‫429 יותר מדי בקשות חרגת מהמכסה היומית שלך. צריך לחכות עד שהמכסה תתאפס או לבקש להגדיל אותה.
too_many_requests ‫429 יותר מדי בקשות שלחת יותר מדי בקשות בפרק זמן קצר. צריך להמתין ולנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
cancelled ‫499 הלקוח סגר את הבקשה הלקוח ביטל את הבקשה לפני שהיא הושלמה. לא נדרשת פעולה. בדרך כלל זה אומר שהלקוח התנתק.
api_error ‫‎500 שגיאת שרת פנימית קרתה שגיאה לא צפויה בשרת. לנסות שוב לשלוח את הבקשה. אם הבעיה נמשכת, פנו לתמיכה.
unimplemented ‫501 לא הוטמע הפעולה או התכונה לא מוטמעות או לא נתמכות. צריך לבדוק את היכולות של ה-API או לעבור לתכונה נתמכת.
service_unavailable ‫‎503 Service Unavailable השירות עמוס או מושבת באופן זמני. צריך להמתין ולנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
deadline_exceeded ‫‎504 Gateway Timeout הבקשה לא הסתיימה במסגרת המועד האחרון. כדי להשתמש בברירת המחדל של השרת, צריך להסיר את הגדרת המועד האחרון של הלקוח או להגדיל אותה.

קודי חסימה של יצירת תוכן

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

קוד תיאור
safety הבקשה נחסמה בגלל הפרות של כללי הבטיחות (תוכן פוגעני).
recitation הבקשה נחסמה בגלל הגבלות על זכויות יוצרים או על דקלום.
language הבקשה נחסמה בגלל שפה לא נתמכת.
prohibited_content הבקשה נחסמה בגלל הנחיות בנושא תוכן אסור.
spii הבקשה נחסמה בגלל הגבלות על פרטים אישיים מזהים בעלי רגישות גבוהה (SPII).
blocklist הבקשה נחסמה בגלל מונחים אסורים ברשימת חסימה.
image_safety הפרות של כללי הבטיחות חסמו את יצירת התמונה.
image_prohibited_content ההנחיות בנושא תוכן אסור חסמו את יצירת התמונה.
image_recitation הגבלות על זכויות יוצרים או על דקלום חסמו את יצירת התמונות.
image_other סיבות לא ידועות חסמו את יצירת התמונה.
content_blocked הבקשה נחסמה מסיבה לא ידועה שקשורה למדיניות.

קודי שגיאה ביצירה

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

קוד תיאור
malformed_function_call המודל יצר בקשה להפעלת פונקציה שלא ניתן היה לנתח.
malformed_tool_call המודל יצר קריאה לכלי שלא ניתן היה לנתח.
unexpected_tool_call המודל הפעיל כלי שלא הוצהר בבקשה.
no_image המודל לא הצליח ליצור תמונה.
too_many_tool_calls המודל יצר יותר קריאות לכלים מהמותר.
missing_thought_signature בתגובה חסרה חתימת מחשבה נדרשת.

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

כל השגיאות מ-Interactions API מחזירות אובייקט error שמכיל code ו-message. לדוגמה, אם מעבירים סוג כלי שלא נתמך, הפונקציה מחזירה:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}
שדה סוג תיאור
code מחרוזת קוד שגיאה בפורמט קריא למכונה ב-snake_case.
message מחרוזת תיאור קריא לאנשים של הבעיה.

איך השגיאות נשלחות

ה-API מחזיר שגיאות בצורה שונה בהתאם לסוג הבקשה: בקשת HTTP רגילה או בקשת סטרימינג (SSE).

בקשות HTTP רגילות

בבקשות רגילות (לא בסטרימינג), ה-API מגדיר את קוד הסטטוס של תגובת ה-HTTP (למשל 400 Bad Request,‏ 401 Unauthorized או 429 Too Many Requests) ומחזיר אובייקט error בגוף התגובה בפורמט JSON:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

בקשות סטרימינג (SSE)

בבקשות סטרימינג (stream: true), ה-API שולח אירועי שגיאה דרך הסטרימינג של Server-Sent Events‏ (SSE) עם event_type שמוגדר ל-"error". השדה error מכיל את אותו מבנה של code ו-message:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

סכימת האירועים המלאה של SSE מפורטת במאמרי העזרה של Interactions API.

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