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

‫Google Calendar API מחזיר שני סוגים של מידע על שגיאות:

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

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

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

במסמכי התיעוד של Google Cloud Storage מוסבר על השהיה מעריכית לפני ניסיון חוזר (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: חריגה מהגבלת הקצב של יצירת בקשות לכל משתמש

הגעתם לאחד מהמגבלות במסוף Google Cloud.

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

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

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

המשתמש הגיע לקצב הבקשות המקסימלי של 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 ועל התשתית שלה מפני התנהגות פוגעת.

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

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

‫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."
  }
}

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