פתרון שגיאות

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

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

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

פתרון שגיאה מסוג 400: בקשה שגויה

השגיאה הזו עשויה לנבוע מהשגיאות הבאות בקוד:

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

הערה: זוהי רשימה חלקית בלבד, ויש מקרים נוספים שעלולים לגרום לשגיאה 400.

הנה דוגמה לייצוג 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: פרטי כניסה לא תקינים

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

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

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

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

פתרון שגיאה מסוג 403: חריגה ממגבלת השימוש

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

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

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

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

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

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

כדי לפתור את השגיאה:

1. נכנסים אל Google API Console.
2. בוחרים את הפרויקט הרצוי.
3. לוחצים על הכרטיסייה Quotas (מכסות).
4. שליחת בקשה להגדלת המכסה. מידע נוסף זמין במאמר בנושא בקשה להגדלת המכסה.

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

פתרון שגיאה 403: חריגה מהגבלת קצב של יצירת בקשות לכל משתמש

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

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

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

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

פתרון שגיאה מסוג 403: חריגה ממגבלת קצב הבקשות

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

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

כדי לפתור את השגיאה, מנסים שוב לשלוח בקשות שנכשלו.

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

פתרון שגיאה 403: אי אפשר להשתמש באפליקציה עם המזהה {appId} בדומיין של המשתמש המאומת

שגיאה 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."
  }
}

כדי לפתור את השגיאה:

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

פתרון שגיאה 429: יותר מדי בקשות

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

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

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

המגבלות האלה הן לכל משתמש, והן משותפות לכל הלקוחות של המשתמש, בין אם מדובר בלקוחות API, בלקוחות מקומיים/אינטרנטיים או ב-SMTP MSA. אם תחרגו מהמגבלות האלה, תוחזר שגיאת HTTP 429 Too Many Requests 'חריגה ממגבלת הקצב למשתמש'(שליחת אימייל) עם הזמן שצריך לחכות עד לניסיון חוזר. חשוב לזכור שאם חורגים מהמגבלות היומיות, יכול להיות שסוגי השגיאות האלה יופיעו למשך כמה שעות לפני שהבקשה תאושר.

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

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

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

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

• ‫‎502 Bad Gateway
• ‫‎503 Service Unavailable
• ‫‎504 Gateway Timeout

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

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

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

הצגה או שינוי של מגבלות השימוש, הגדלת המכסה

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

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

בקשות באצווה

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