דף זה תורגם על ידי Cloud Translation API.

טיפול בשגיאות 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: User Rate Limit Exceeded

הגעתם לאחת מהמגבלות שמפורטות ב-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: Rate Limit Exceeded

המשתמש הגיע לקצב הבקשות המקסימלי של 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: Calendar usage limits exceeded

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

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

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

מידע נוסף על מגבלות השימוש ביומן Google זמין במרכז העזרה לאדמינים של 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."
 }
}

הצעה לפעולה: צריך ליצור מזהה חדש אם רוצים ליצור מופע חדש, אחרת צריך להשתמש בקריאה ל-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: Too many requests

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

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

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

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

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

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