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

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

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

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

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

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

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

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

בקטע הזה מופיע ייצוג מלא ב-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 Calendar שנועדו להגן על משתמשי Google ועל התשתית מפני התנהלות פוגענית.

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

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

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

‫403: Forbidden for non-organizer

הבקשה לעדכון האירוע מנסה להגדיר אחת מהמאפיינים המשותפים של האירוע בעותק שלא שייך למארגן. רק מארגני הפגישה יכולים להגדיר מאפיינים משותפים (לדוגמה, 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": "Not Found" } ], "code": 404, "message": "Not Found" } }

הצעה לפעולה: שימוש בהשהיה מעריכית לפני ניסיון חוזר (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: Precondition Failed

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

{
 "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).