פתרון שגיאות

‫Gmail API מחזיר שני רמות של מידע על שגיאות:

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

אפליקציית Gmail צריכה לזהות ולטפל בכל השגיאות שעלולות להתרחש כשמשתמשים ב-API בארכיטקטורת REST. במדריך הזה מוסבר איך לפתור שגיאות ספציפיות ב-Gmail API.

סיכום קודי סטטוס של HTTP

קוד שגיאה	תיאור
`200 - OK`	הבקשה מצליחה (זו התגובה הרגילה לבקשות HTTP מוצלחות).
`400 - Bad Request`	אי אפשר למלא את הבקשה בגלל שגיאה בצד הלקוח בבקשה.
`401 - Unauthorized`	הבקשה מכילה פרטי כניסה לא תקינים.
`403 - Forbidden`	הבקשה התקבלה והובנה, אבל למשתמש אין הרשאה לבצע את הבקשה.
`404 - Not Found`	לא הצלחנו למצוא את הדף שביקשת.
`429 - Too Many Requests`	יותר מדי בקשות ל-API.
`500, 502, 503, 504 - Server Errors`	אירעה שגיאה לא צפויה במהלך עיבוד הבקשה.

שגיאות 400

השגיאות האלה מציינות שיש שגיאה בבקשה, לרוב בגלל פרמטר חובה חסר.

`badRequest`

השגיאה הזו יכולה להופיע בגלל אחת מהבעיות הבאות בקוד:

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

דוגמת ה-JSON הבאה מייצגת את השגיאה הזו:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

כדי לפתור את השגיאה הזו, צריך לבדוק את השדה message ולשנות את הקוד בהתאם.

שגיאות 401

השגיאות האלה מציינות שהבקשה לא מכילה אסימון גישה תקין.

`authError`

השגיאה הזו מתרחשת כשפג התוקף של טוקן הגישה שבו אתם משתמשים או שהוא לא תקין. השגיאה הזו יכולה להיגרם גם בגלל הרשאות חסרות להיקפי ההרשאות המבוקשים. דוגמת ה-JSON הבאה מייצגת את השגיאה הזו:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

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

מידע נוסף על המגבלות ב-Gmail זמין במאמר בנושא מגבלות שימוש.

שגיאות 403

השגיאות האלה מתרחשות כשחורגים ממגבלת שימוש או כשאין למשתמש את ההרשאות הנכונות. כדי לזהות את הגורם לבעיה, בודקים את השדה reason בקובץ ה-JSON שמוחזר. השגיאה הזו מתרחשת במצבים הבאים:

אי אפשר להשתמש באפליקציה בדומיין של המשתמש המאומת.
הייתה חריגה מהמגבלה היומית.
הייתה חריגה מהגבלת הקצב של יצירת בקשות לכל משתמש.
הייתה חריגה מהגבלת הקצב של יצירת בקשות בפרויקט.

מידע נוסף מופיע במאמר בנושא מגבלות שימוש.

`dailyLimitExceeded`

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

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

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

`domainPolicy`

השגיאה הזו מתרחשת כשהמדיניות של הדומיין של המשתמש לא מאפשרת לאפליקציה שלכם לגשת ל-Gmail. קובץ ה-JSON הבא מייצג את השגיאה הזו:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

כדי לפתור את השגיאה, אפשר לנסות את הפעולות הבאות:

צריך להודיע למשתמש שהדומיין לא מאפשר לאפליקציה שלך לגשת ל-Gmail.
מנחים את המשתמש לפנות לאדמין בדומיין שלו כדי לבקש גישה לאפליקציה.

`rateLimitExceeded`

השגיאה הזו מציינת שהמשתמש הגיע לקצב הבקשות המקסימלי של Gmail API. המגבלה הזו משתנה בהתאם לסוג הבקשה. דוגמת ה-JSON הבאה מייצגת את השגיאה הזו:

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

כדי לפתור את השגיאה, אפשר לנסות את הפעולות הבאות:

מגישים בקשה להגדלת המכסה.
כדאי להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב את הבקשה.

`userRateLimitExceeded`

השגיאה הזו מתרחשת כשמגיעים למגבלה לכל משתמש. הנה דוגמה ל-JSON שמייצגת את השגיאה הזו:

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

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

שגיאות 429

שגיאה 429 Too many requests (יותר מדי בקשות) יכולה להתרחש בגלל מגבלות יומיות לכל משתמש (כולל מגבלות על שליחת אימייל), מגבלות רוחב פס או מגבלת בקשות בו-זמניות לכל משתמש. בהמשך מפורט מידע על כל מגבלה. עם זאת, אפשר לפתור את הבעיה בכל אחת מהמגבלות האלה על ידי ניסיון חוזר לשליחת בקשות שנכשלו או על ידי פיצול העיבוד בין כמה חשבונות Gmail.

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

מגבלות על שליחת אימיילים

מגבלות השליחה היומיות הרגילות חלות על Gmail API. ההגבלות האלה שונות עבור משתמשי Google Workspace בתשלום ועבור משתמשי Gmail.com בגרסת ניסיון. מידע על המגבלות האלה מופיע במאמר מגבלות שליחה שמוגדרות למשתמשי Gmail ב-Google Workspace.

המגבלות האלה הן לכל משתמש, והן משותפות לכל הלקוחות של המשתמש, בין אם מדובר בלקוחות API, בלקוחות מובנים או בלקוחות אינטרנט, או ב-SMTP MSA. אם תחרגו מהמגבלות האלה, תוחזר שגיאת HTTP 429 ‏Too many requests: User-rate limit exceeded (Mail sending)‎ (יותר מדי בקשות: חריגה ממגבלת הקצב למשתמש (שליחת אימייל)) עם זמן לניסיון חוזר. אם חורגים מהמגבלות היומיות, יכול להיות שתקבלו את השגיאות האלה במשך כמה שעות לפני שהבקשה תאושר.

פייפליין שליחת האימייל מורכב: אם המשתמש חורג מהמכסה שלו, יכול להיות שיעברו כמה דקות עד שה-API יתחיל להחזיר תשובות עם שגיאה 429. אי אפשר להניח שתגובה 200 פירושה שהאימייל נשלח בהצלחה.

מגבלות על רוחב הפס

ל-API יש מגבלות רוחב פס להעלאה ולהורדה לכל משתמש, ששווות למגבלות של IMAP אבל לא תלויות בהן. המגבלות האלה משותפות לכל הלקוחות של Gmail API עבור משתמש.

בדרך כלל מגיעים למגבלות האלה רק במצבים חריגים או במקרים של התנהלות פוגעת. אם חורגים מהמגבלות האלה, מוחזרת שגיאת HTTP 429 Too many requests: User-rate limit exceeded (יותר מדי בקשות: חריגה ממגבלת הקצב למשתמש) עם זמן לניסיון חוזר. חריגה מהמגבלות היומיות עלולה לגרום לשגיאות האלה למשך כמה שעות לפני שהבקשה תאושר.

בקשות מקבילות

ב-Gmail API יש מגבלה על מספר הבקשות המקבילות לכל משתמש (בנוסף למגבלת הקצב לכל משתמש). המגבלה הזו משותפת לכל לקוחות Gmail API שגולשים למשתמש, והיא מבטיחה שאף לקוח API לא יגרום לעומס יתר על תיבת הדואר של משתמש Gmail או על שרת הקצה העורפי שלו.

השגיאה הזו יכולה להופיע אם שולחים הרבה בקשות מקבילות עבור משתמש יחיד, או אם שולחים קבוצות של בקשות עם מספר גדול של בקשות. גם מספר גדול של לקוחות API עצמאיים שניגשים לתיבת הדואר של משתמש Gmail בו-זמנית יכול להפעיל את השגיאה הזו. אם חורגים מהמגבלה הזו, מוחזרת שגיאת HTTP 429 ‏Too many requests: Too many concurrent requests for user (יותר מדי בקשות: יותר מדי בקשות בו-זמנית למשתמש).

שגיאות 500,‏ 502,‏ 503 ו-504

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

רשימה של שגיאות 5xx:

‫500 שגיאת קצה עורפי
‫‎502 Bad Gateway
‫‎503 Service Unavailable
‫‎504 Gateway Timeout

backendError

השגיאה הזו מתרחשת כשיש שגיאה לא צפויה במהלך עיבוד הבקשה. דוגמת ה-JSON הבאה מייצגת את השגיאה הזו:

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

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

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

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

תקופות הניסיון החוזר צריכות להתחיל לפחות שנייה אחת אחרי השגיאה.

ניהול המגבלות במכסות

כדי לראות או לשנות את מגבלות השימוש בפרויקט, או כדי לבקש להגדיל את המכסה:

אם עדיין אין לכם חשבון לחיוב לפרויקט, אתם צריכים ליצור חשבון כזה.
נכנסים לדף Enabled APIs (ממשקי API מופעלים) ב-API library ב-קונסולה לממשקי API ובוחרים API מהרשימה.
כדי לראות ולשנות הגדרות שקשורות למכסות, בוחרים באפשרות מכסות. כדי לראות את נתוני השימוש, בוחרים באפשרות שימוש.

למידע נוסף, אפשר לקרוא את המאמר בנושא איך רואים ומנהלים את המכסות.

בקשות באצווה

מומלץ להשתמש בבקשות באצווה, אבל סביר להניח שגודל אצווה גדול יותר יפעיל הגבלת קצב של יצירת בקשות. לא מומלץ לשלוח אצוות עם יותר מ-50 בקשות. מידע על שליחת בקשות באצווה מופיע במאמר בקשות באצווה.