שגיאות ומגבלות

השגיאה מגיעה בפורמט של ה-API שאליו פניתם: האובייקט error עבור OpenAI, {"type": "error", "error": {...}} עבור Anthropic, וכן error עם השדות status וכן details עבור Gemini. לכן ערכות SDK מזהות אותן כשגיאות API רגילות.

• error.code וכן error.reason — מחלקת השגיאה מהטבלה שלהלן; שני השדות תואמים. error.type — הערך הרגיל של הפורמט (לדוגמה, invalid_request_error או server_error).
• error.request_id (ב-Anthropic — request_id ברמה העליונה), הכותרת X-Request-ID וסוף הודעת השגיאה מציינים את מזהה הבקשה.
• ב-Gemini, המחלקה נמצאת ב- error.details: ErrorInfo.reason — אותו קוד באותיות גדולות (לדוגמה, MODEL_OVERLOADED), domain — ailoot.ai; מזהה הבקשה נמצא ב- RequestInfo.requestId.
• בפורמט Gemini, שגיאת 5xx שאין לשלוח מחדש אוטומטית וגם result_pending_check מגיעים עם סטטוס 409 ועם status ABORTED: כך Gemini SDK ו-CLI אינם שולחים אותן מחדש בעצמם. מחלקת השגיאה נמצאת ב- ErrorInfo.reason (לדוגמה, MODEL_TIMEOUT או RESULT_PENDING_CHECK).
• בתשובה בפורמט OpenAI יש גם שדות ברמה העליונה code וכן message — עבור לקוחות ישנים.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

הקודים של תשובות המודל ושל בדיקת התוצאה (502, 503 ו-504) מציינים כעת את המודל או את הבקשה: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed וכן result_pending_check. אם הקוד שלכם משווה את error.code לערכים הישנים, החליפו אותם בקודים מהטבלה; את ההתאמה בין הקודים הישנים לחדשים תסביר התמיכה.

• תחילה בדקו את X-Should-Retry ואת מחלקת השגיאה: כאשר מתקבל false, result_pending_check או model_timeout אל תשלחו שוב אוטומטית. מצאו את ה-Request ID בהיסטוריית האזור האישי: שם מופיעים התוצאה והחיוב.
• שליחה חוזרת בטוחה כשמתקבל X-Should-Retry: true: המתינו Retry-After שניות. ב-5xx, הקוד לבדו אינו מספיק: ייתכן שהתוצאה כבר הופיעה. בדקו תחילה את ההיסטוריה באזור האישי או פנו לתמיכה עם Request ID. הדבר חשוב במיוחד לתמונות, וידאו, מוזיקה וצעדים ארוכים של סוכנים.
• שליחה חוזרת לא תעזור: 400, 401, 402, 403, 404 — תקנו תחילה את הבקשה, המפתח או היתרה.

קצב הבקשות ומספר הבקשות בו-זמניות מוגבלים לכל החשבון שלכם, ולא למפתח יחיד. חריגה מחזירה 429 rate_limit_exceeded עם הכותרת Retry-After: 10. אם המודל עצמו עמוס — 503 model_overloaded עם Retry-After: 30. אם נדרשת קיבולת גבוהה יותר, פנו ל- תמיכה.

מגבלות ההוצאות מוגדרות במפתח: המגבלה הכוללת — 402 api_key_quota_exhausted, וחלונות של 5 שעות, 1 יום ו-7 ימים — 429 usage_limit_reached. פרטים נוספים — מפתחות וכתובת ה-API.

אפשר לבקש את רשימת המודלים גם ביתרה של אפס; ליצירה נדרשת יתרה לרזרבה. מודלי NVIDIA (Nemotron ואחרים) פועלים דרך תור משותף: בעומס גבוה התשובה עשויה להגיע מאוחר יותר או שתוחזר השגיאה "המודל עמוס זמנית" עם הכותרת Retry-After — נסו שוב לאחר הזמן המצוין. המחירים מופיעים בקטלוג והחיוב זהה לזה של המודלים האחרים.

המודל קובע את מגבלות הגודל: חלון ההקשר (מספר הטוקנים שאפשר לשלוח) ואורך התשובה המרבי. הן מופיעות ב- קטלוג.