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

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

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

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

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

במסמכי התיעוד של Cloud APIs יש הסבר טוב על השהיה מעריכית לפני ניסיון חוזר (exponential backoff) ואיך להשתמש בה עם ממשקי 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 לכל יומן Google או לכל משתמש מאומת.

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

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

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

המשתמש הגיע לאחת מהמגבלות של יומן Google שנועדו להגן על משתמשי 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": "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."
 }
}

פעולה מומלצת: אם רוצים ליצור מופע חדש, צריך ליצור מזהה חדש. אחרת, צריך להשתמש בהפעלת method 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) לפני ניסיון חוזר.