‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

פתרון שגיאות

‫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 'יותר מדי בקשות' יכולה להתרחש בגלל מגבלות יומיות לכל משתמש (כולל מגבלות על שליחת אימייל), מגבלות רוחב פס או מגבלות על מספר הבקשות המקבילות לכל משתמש. בהמשך מפורט מידע על כל מגבלה. עם זאת, אפשר לפתור את הבעיה בכל אחת מהמגבלות האלה על ידי ניסיון חוזר לשליחת בקשות שנכשלו או על ידי פיצול העיבוד בין כמה חשבונות Gmail.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

‫500 שגיאת קצה עורפי
‫502 שער שגוי
‫503 השירות לא זמין
‫504 הזמן שהוקצב לשער חלף

`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 בקשות. מידע על שליחת בקשות באצווה זמין במאמר בנושא בקשות באצווה.