שגיאות API

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

קודי שגיאה של Standard API

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

קוד סטטוס HTTP תיאור הפעולה המומלצת
invalid_request ‫400 בקשה שגויה הפורמט של הבקשה שגוי או שהיא מכילה פרמטרים לא תקינים. בודקים את נתוני הקלט מול הפניית ה-API.
parameter_unknown ‫400 בקשה שגויה הבקשה מכילה פרמטר לא מוכר. צריך להסיר את הפרמטר הלא מזוהה ולנסות שוב.
authentication ‫401 אין הרשאה מפתח ה-API חסר או לא תקין. מאמתים את מפתח ה-API.
permission_denied ‫403 Forbidden למפתח ה-API שלך אין הרשאה למשאב הזה. בודקים את ההרשאות של מפתח ה-API ואת הגישה לפרויקט.
not_found שגיאת 404 המשאב המבוקש לא נמצא. בודקים את נתיב המשאב והפרמטרים.
model_not_found שגיאת 404 המודל שצוין לא נמצא. צריך לאמת את שם המודל או להשתמש במודל אחר.
rate_limit_exceeded ‫429 Too Many Requests חרגתם מהמגבלה של בקשות או טוקנים לדקה או לשנייה. צריך להמתין ולנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).
quota_exceeded ‫429 Too Many Requests חרגתם מהמכסה היומית. צריך לחכות עד שהמכסה תתאפס או לבקש להגדיל את המכסה.
cancelled ‫499 Client Closed Request הלקוח ביטל את הבקשה לפני שהיא הושלמה. אין צורך בפעולה נוספת. בדרך כלל זה אומר שהלקוח התנתק.
api_error ‫‎500 Internal Server Error קרתה שגיאה לא צפויה בשרת. מנסים לשלוח את הבקשה שוב. אם הבעיה נמשכת, אפשר לפנות לתמיכה.
service_unavailable ‫‎503 Service Unavailable השירות עמוס מדי או מושבת באופן זמני. צריך להמתין ולנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

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

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

קוד תיאור
safety הבקשה נחסמה בגלל הפרות של כללי הבטיחות (תוכן פוגעני).
recitation הבקשה נחסמה בגלל הגבלות על זכויות יוצרים או על הקראה.
language הבקשה נחסמה בגלל שפה שלא נתמכת.
prohibited_content הבקשה נחסמה בגלל הנחיות לתוכן אסור.
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) עם הערך "error" של event_type. השדה error מכיל את אותו מבנה של code ושל message:

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

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

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