פתרון שגיאות

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

• קודי שגיאה והודעות של 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: יותר מדי בקשות

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

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

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

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

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

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

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

לרוב, המגבלות האלה חלות רק במקרים חריגים או פוגעניים. אם יש חריגה מהמגבלות האלה, תוחזר השגיאה "חריגה ממגבלת קצב המשתמש" מסוג HTTP 429 Too Many Requests עם זמן ניסיון חוזר. הערה: חריגה מהמגבלות היומיות עלולה לגרום לשגיאות כאלה למשך כמה שעות עד שהבקשה תאושר.

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

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

שליחת בקשות רבות במקביל למשתמש יחיד או שליחת קבוצות עם מספר גדול של בקשות יכולות לגרום לשגיאה הזו. מספר גדול של לקוחות API עצמאיים שניגשים בו-זמנית לתיבת הדואר של המשתמש ב-Gmail יכולים לגרום לשגיאה הזו. אם יש חריגה מהמגבלה הזו, תוחזר השגיאה "יותר מדי בקשות בו-זמניות למשתמש" מסוג HTTP 429 Too Many Requests.

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

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

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

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

• 502 Bad Gateway
• 503 שירות לא זמין
• תם הזמן הקצוב לתפוגה של שער 504

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

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

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

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

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

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

בקשות אצווה

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