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

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

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

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

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

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

במסמכי התיעוד של Cloud APIs יש הסבר מועיל לגבי השהיה מעריכית והסבר על השימוש בה עם ממשקי ה-API של Google.

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

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

400: בקשה שגויה

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

{
 "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: חריגה ממגבלת קצב

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

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

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

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": "לא נמצא" } }

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

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

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

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

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

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 – כרגע הן דומות מבחינה פונקציונלית וצריך להגיב להן באותו אופן באמצעות השהיה מעריכית. בנוסף, חשוב לוודא שהאפליקציה פועלת בהתאם לשיטות המומלצות בקטע ניהול מכסות.

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

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

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

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