פתרון שגיאות

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

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

אפליקציות Gmail צריכות לזהות ולטפל בכל השגיאות שעשויות להתרחש במהלך השימוש ב-API ל-REST. במדריך הזה מפורטות הוראות לפתרון שגיאות 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.
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: Too many requests

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

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

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

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

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

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

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

בדרך כלל, המגבלות האלה מופעלות רק במצבים חריגים או במקרים של ניצול לרעה. אם תחרגו מהמגבלות האלה, תוחזר הודעת השגיאה Too Many Requests‏ HTTP 429 "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

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

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

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

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

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

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

בקשות באצווה

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