טיפול בשגיאות API

ה-API של היומן מחזיר שתי רמות של מידע על השגיאה:

• קודים של שגיאות HTTP והודעות בכותרת
• אובייקט JSON בגוף התגובה עם פרטים נוספים שיכולים לעזור לכם לקבוע איך לטפל בשגיאה.

בהמשך הדף הזה תוכלו למצוא פירוט של שגיאות ביומן Google ודרכים לטפל בהן באפליקציה.

מומלץ מאוד לבדוק טיפול בשגיאות באפליקציה בסביבה אמיתית.

הטמעת השהיה מעריכית לפני ניסיון חוזר (exponential backoff)

במשאבי העזרה של Cloud APIs יש הסבר טוב על השהיה מעריכית לפני ניסיון חוזר (exponential backoff) ואיך להשתמש בו עם ממשקי ה-API של Google.

שגיאות והצעות לפעולות

בקטע הזה מוצג הייצוג המלא של כל שגיאה שמופיעה ב-JSON, והצעות לפעולות שאפשר לבצע כדי לטפל בה.

‏‎400: Bad Request

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

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "timeRangeEmpty",
    "message": "The specified time range is empty.",
    "locationType": "parameter",
    "location": "timeMax",
   }
  ],
  "code": 400,
  "message": "The specified time range is empty."
 }
}

הצעה לפעולה: זוהי שגיאה קבועה, לכן אין לנסות שוב. עליכם לקרוא את הודעת השגיאה ולשנות את הבקשה בהתאם.

401: פרטי כניסה לא חוקיים

כותרת ההרשאה לא חוקית. פג תוקפו של אסימון הגישה שלך או שהוא לא חוקי.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "authError",
    "message": "Invalid Credentials",
    "locationType": "header",
    "location": "Authorization",
   }
  ],
  "code": 401,
  "message": "Invalid Credentials"
 }
}

הצעות לפעולות:

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

403: חרגת ממגבלת קצב המשתמשים

הגעת לאחת המגבלות ב-Developer Console.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

הצעות לפעולות:

• חשוב לוודא שהאפליקציה פועלת בהתאם לשיטות המומלצות מתוך ניהול המכסות.
• הגדלת המכסה למשתמש בפרויקט Developer Console.
• אם משתמש אחד שולח הרבה בקשות מטעם משתמשים רבים בחשבון Google Workspace, כדאי לשקול להשתמש בחשבון שירות עם הענקת גישה ברמת הדומיין ולהגדיר את הפרמטר quotaUser.
• משתמשים בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff).

403: חריגה ממגבלת קצב

המשתמש הגיע לקצב הבקשות המקסימלי של Google Calendar API או לכל משתמש מאומת.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "rateLimitExceeded",
    "message": "Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

הצעה לפעולה: שגיאות rateLimitExceeded יכולות להחזיר קודי שגיאה 403 או 429 – כרגע הן דומות מבחינה פונקציונלית ויש להגיב עליהן באותו אופן באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). בנוסף, חשוב לוודא שהאפליקציה פועלת בהתאם לשיטות המומלצות מתוך ניהול המכסות.

403: חריגה ממגבלות השימוש ביומן

המשתמש הגיע לאחת המגבלות של יומן Google כדי להגן על התשתיות ועל המשתמשים ב-Google מפני התנהגות פוגענית.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

הצעות לפעולות:

• בעזרה לאדמינים ב-Google Workspace תוכלו לקרוא מידע נוסף על מגבלות השימוש ביומן.

403: אסור למי שאינו מארגן

הבקשה לעדכון האירוע מנסה להגדיר אחד ממאפייני האירוע המשותפים בעותק שאינו של המארגן. רק המארגן יכול להגדיר נכסים משותפים (לדוגמה, guestsCanInviteOthers, guestsCanModify או guestsCanSeeOtherGuests).

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "forbiddenForNonOrganizer",
    "message": "Shared properties can only be changed by the organizer of the event."
   }
  ],
  "code": 403,
  "message": "Shared properties can only be changed by the organizer of the event."
 }
}

הצעות לפעולות:

• במקרה שאתם משתמשים ב-Events: insert, ב-Events: Import או ב-Events: update, והבקשה לא כוללת מאפיינים משותפים, הפעולה הזו זהה לנסות להגדיר אותם לערכי ברירת המחדל. במקום זאת, כדאי להשתמש ב-Events: patch.
• אם הבקשה כוללת נכסים משותפים, עליכם לוודא שאתם מנסים לשנות את המאפיינים האלה רק אם אתם מעדכנים את העותק של המארגן.

404: לא נמצא

המשאב שצוין לא נמצא. מצב כזה יכול לקרות בכמה מקרים. הנה כמה דוגמאות:

• כשהמשאב המבוקש (עם המזהה שסופק) מעולם לא היה קיים

• כאשר ניגשים ליומן שהמשתמש לא יכול לגשת אליו

  { "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "לא נמצא" } ], "code": 404, "message": "לא נמצא" } }

הצעה לפעולה: משתמשים בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff).

409: המזהה המבוקש כבר קיים

באחסון עצמו קיימת כבר מכונה עם המזהה הזה.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "duplicate",
    "message": "The requested identifier already exists."
   }
  ],
  "code": 409,
  "message": "The requested identifier already exists."
 }
}

הצעה לפעולה: תוכלו ליצור מזהה חדש אם רוצים ליצור מכונה חדשה, ואם לא רוצים להשתמש בקריאה לשיטת update.

‏‎409: Conflict

אי אפשר לבצע פריט אצווה בתוך פעולה events.batch בגלל התנגשות תפעולית עם פריטים אחרים שהתבקשו לאצוות.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conflict",
    "message": "Conflict"
   }
  ],
  "code": 409,
  "message": "Conflict"
 }
}

הצעה לפעולה: כדאי להחריג את כל הפריטים שסיימתם בהצלחה ואת כל הפריטים המקובצים שנכשלו, ולנסות שוב את שאר הפריטים ב-events.batch אחר או בפעולות מתאימות של אירוע יחיד.

410: Gone

הפרמטרים syncToken או updatedMin לא חוקיים יותר. השגיאה הזו יכולה גם לקרות אם בקשה מנסה למחוק אירוע שכבר נמחק.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "fullSyncRequired",
    "message": "Sync token is no longer valid, a full sync is required.",
    "locationType": "parameter",
    "location": "syncToken",
    }
  ],
  "code": 410,
  "message": "Sync token is no longer valid, a full sync is required."
 }
}

או

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "updatedMinTooLongAgo",
    "message": "The requested minimum modification time lies too far in the past.",
    "locationType": "parameter",
    "location": "updatedMin",
   }
  ],
  "code": 410,
  "message": "The requested minimum modification time lies too far in the past."
 }
}

או

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "deleted",
    "message": "Resource has been deleted"
   }
  ],
  "code": 410,
  "message": "Resource has been deleted"
 }
}

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

412: התנאי המוקדם נכשל

ה-etag שסופק בכותרת If-match לא תואם יותר לתג הנוכחי של המשאב.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conditionNotMet",
    "message": "Precondition Failed",
    "locationType": "header",
    "location": "If-Match",
    }
  ],
  "code": 412,
  "message": "Precondition Failed"
 }
}

פעולה מומלצת: שליפה מחדש של הישות והחלה מחדש של השינויים. פרטים נוספים זמינים במאמר קבלת גרסאות ספציפיות של משאבים.

429: יותר מדי בקשות

השגיאה rateLimitExceeded מתרחשת כשמשתמש שולח יותר מדי בקשות בפרק זמן נתון.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "rateLimitExceeded",
        "message": "Rate Limit Exceeded"
      }
    ],
    "code": 429,
    "message": "Rate Limit Exceeded"
  }
}

הצעה לפעולה: שגיאות rateLimitExceeded יכולות להחזיר קודי שגיאה 403 או 429 – כרגע הן דומות מבחינה פונקציונלית ויש להגיב עליהן באותו אופן באמצעות השהיה מעריכית לפני ניסיון חוזר (exponential backoff). בנוסף, חשוב לוודא שהאפליקציה פועלת בהתאם לשיטות המומלצות מתוך ניהול המכסות.

500: שגיאת קצה עורפי

אירעה שגיאה לא צפויה במהלך עיבוד הבקשה.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

הצעה לפעולה: משתמשים בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff).