קודי שגיאה של FCM

קודי שגיאה של REST ל-HTTP v1 API

תגובות שגיאת HTTP ל-HTTP v1 API מכילות קוד שגיאה, הודעת שגיאה וסטטוס שגיאה. הם יכולים גם להכיל מערך details עם פרטים נוספים על השגיאה.

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

דוגמה 1: תגובת שגיאה מבקשת HTTP v1 API עם ערך לא חוקי בהודעת נתונים

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "message.data[0].value",
            "description": "Invalid value at 'message.data[0].value' (TYPE_STRING), 12"
          }
        ]
      }
    ]
  }
}

דוגמה 2: תגובת שגיאה מבקשת HTTP v1 API עם אסימון רישום לא חוקי

{
  "error": {
    "code": 400,
    "message": "The registration token is not a valid FCM registration token",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "INVALID_ARGUMENT"
      }
    ]
   }
}

שימו לב שלשתי ההודעות יש את אותו קוד וסטטוס, אבל מערך הפרטים מכיל ערכים מסוגים שונים. בדוגמה הראשונה, הסוג הוא type.googleapis.com/google.rpc.BadRequest, מה שמצביע על שגיאה בערכי הבקשה. בדוגמה השנייה, עם הסוג type.googleapis.com/google.firebase.fcm.v1.FcmError, יש שגיאה ספציפית ל-FCM. בהרבה שגיאות, מערך הפרטים מכיל את המידע שדרוש לניפוי באגים ולמציאת פתרון.

בטבלה הבאה מפורטים קודי השגיאה של FCM v1 API בארכיטקטורת REST והתיאורים שלהם.

קוד שגיאה	תיאור והשלבים לפתרון הבעיה
UNSPECIFIED_ERROR אין מידע נוסף על השגיאה הזו.	אין.
‫INVALID_ARGUMENT (קוד שגיאת HTTP‏ = 400) פרמטרים לא תקינים של הבקשה. תוסף מסוג google.rpc.BadRequest מוחזר כדי לציין איזה שדה לא היה תקין.	יכולות להיות כמה סיבות לכך, כולל רישום לא תקין, שם חבילה לא תקין, הודעה גדולה מדי, מפתח נתונים לא תקין, TTL לא תקין או פרמטרים אחרים לא תקינים. רישום לא תקין: בודקים את הפורמט של אסימון הרישום שמועבר לשרת. חשוב לוודא שהוא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת מהרישום ב-FCM. אל תקצרו את הטוקן ואל תוסיפו תווים. שם החבילה לא תקין: ודאו שההודעה נשלחה לאסימון רישום ששם החבילה שלו תואם לערך שהועבר בבקשה. ההודעה גדולה מדי: צריך לוודא שהגודל הכולל של נתוני המטען הייעודי (payload) שכלולים בהודעה לא חורג מהמגבלות של FCM: ‏4,096 בייטים לרוב ההודעות, או 2,048 בייטים במקרה של הודעות לנושאים. ההגבלה הזו כוללת גם את המפתחות וגם את הערכים. מפתח נתונים לא חוקי: צריך לוודא שנתוני המטען הייעודי (payload) לא מכילים מפתח (כמו from או gcm, או כל ערך עם הקידומת google) שמשמש באופן פנימי את FCM. שימו לב שיש מילים (כמו collapse_key) שגם FCM משתמש בהן, אבל מותר להשתמש בהן במטען הייעודי (payload). במקרה כזה, הערך של FCM יחליף את הערך של המטען הייעודי. TTL לא חוקי: צריך לוודא שהערך שמשמש ב-TTL הוא מספר שלם שמייצג משך זמן בשניות בין 0 ל-2,419,200 (4 שבועות). פרמטרים לא תקינים: צריך לוודא שהשם והסוג של הפרמטרים שצוינו נכונים.
UNREGISTERED (קוד שגיאת HTTP‏ = 404) הרישום של מופע האפליקציה בוטל ב-FCM. בדרך כלל זה אומר שהאסימון שבו השתמשתם כבר לא תקף, וצריך להשתמש באסימון חדש.	השגיאה הזו יכולה להיגרם בגלל אסימוני רישום חסרים או אסימונים לא רשומים. רישום חסר: אם היעד של ההודעה הוא ערך token, צריך לוודא שהבקשה מכילה אסימון רישום. לא רשום: אסימון רישום קיים עשוי להפסיק להיות תקף בכמה תרחישים, כולל: - אם אפליקציית הלקוח מבטלת את הרישום ב-FCM. - אם הרישום של אפליקציית הלקוח מבוטל באופן אוטומטי, למשל אם המשתמש מסיר את האפליקציה. לדוגמה, ב-iOS, אם שירות המשוב של APNs דיווח שהאסימון של APNs לא תקין. - אם פג התוקף של אסימון הרישום (לדוגמה, Google עשויה להחליט לרענן את אסימוני הרישום, או שפג התוקף של אסימון ה-APNs במכשירי iOS). - אם אפליקציית הלקוח מעודכנת אבל הגרסה החדשה לא מוגדרת לקבלת הודעות. בכל המקרים האלה, צריך להסיר את אסימון הרישום הזה משרת האפליקציה ולהפסיק להשתמש בו כדי לשלוח הודעות.
SENDER_ID_MISMATCH (קוד שגיאת HTTP‏ = 403) מזהה השולח המאומת שונה ממזהה השולח של אסימון הרישום.	טוקן רישום מקושר לקבוצה מסוימת של שולחים. כשרושמים אפליקציית לקוח ל-FCM, צריך לציין אילו שולחים מורשים לשלוח הודעות. צריך להשתמש באחד ממזהי השולח האלה כששולחים הודעות לאפליקציית הלקוח. אם תעברו לשולח אחר, אסימוני הרישום הקיימים לא יפעלו.
QUOTA_EXCEEDED (קוד שגיאת HTTP‏ = 429) חריגה ממגבלת השליחה ליעד ההודעה. מוחזרת הרחבה מסוג google.rpc.QuotaFailure כדי לציין איזו מכסה חרגה.	השגיאה הזו יכולה להיגרם כתוצאה מחריגה ממכסת קצב ההודעות, ממכסת קצב ההודעות במכשיר או ממכסת קצב ההודעות בנושא. חריגה מקצב שליחת ההודעות: קצב שליחת ההודעות גבוה מדי. צריך להפחית את קצב השליחה הכולל של ההודעות. כדי לנסות לשלוח מחדש הודעות שנדחו, צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם עיכוב ראשוני מינימלי של דקה אחת. Device message rate exceeded: קצב ההודעות למכשיר מסוים גבוה מדי. מידע על מגבלת קצב ההודעות למכשיר אחד צריך להפחית את מספר ההודעות שנשלחות למכשיר הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב. חריגה מקצב ההודעות בנושא: קצב ההודעות למנויים בנושא מסוים גבוה מדי. צריך להפחית את מספר ההודעות שנשלחות בנושא הזה, ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם השהיה ראשונית של דקה אחת לפחות לפני שמנסים לשלוח שוב.
‫UNAVAILABLE (קוד שגיאת HTTP‏ = 503) השרת עמוס.	השרת לא הצליח לעבד את הבקשה בזמן. נסו שוב את אותה בקשה, אבל: - צריך לפעול לפי הכותרת Retry-After אם היא כלולה בתגובה משרת החיבור של FCM. - מטמיעים השהיה מעריכית לפני ניסיון חוזר (exponential backoff) במנגנון הניסיון החוזר. (לדוגמה, אם המתנתם שנייה אחת לפני הניסיון החוזר הראשון, המתינו לפחות שתי שניות לפני הניסיון הבא, לאחר מכן 4 שניות וכן הלאה). אם אתם שולחים כמה הודעות, כדאי להשתמש ב-jittering. מידע נוסף זמין במאמר טיפול בניסיונות חוזרים, או ב לוח הבקרה של סטטוס FCM כדי לזהות אם יש שיבושים מתמשכים בשירות שמשפיעים על FCM. שולחים שגורמים לבעיות עלולים להיכנס לרשימת החסימה.
‫INTERNAL (קוד שגיאת HTTP‏ = 500) אירעה שגיאה פנימית לא ידועה.	השרת נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות שוב את אותה בקשה לפי ההצעות שמפורטות בקטע טיפול בניסיונות חוזרים או לבדוק את לוח הבקרה של סטטוס FCM. כדי לבדוק אם יש שיבושים בשירות שמשפיעים על FCM. אם השגיאה נמשכת, צריך לפנות לתמיכה של Firebase.
‫THIRD_PARTY_AUTH_ERROR (קוד שגיאת HTTP‏ = 401) אישור APNs או מפתח אימות של התראות אינטרנט חסר או לא תקין.	לא ניתן היה לשלוח הודעה שמטורגטת למכשיר iOS או לרישום של התראות מאתרים. בודקים את התקינות של פרטי הכניסה לפיתוח ולייצור.

קודי שגיאה של SDK לאדמינים

בטבלה הבאה מפורטים קודי השגיאה של Firebase Admin FCM API והתיאורים שלהם, כולל השלבים המומלצים לפתרון הבעיה.

קוד שגיאה	תיאור והשלבים לפתרון הבעיה
messaging/invalid-argument	הועבר ארגומנט לא תקין לשיטת FCM. הודעת השגיאה אמורה להכיל מידע נוסף.
messaging/invalid-recipient	הנמען של ההודעה לא תקין. הודעת השגיאה אמורה לכלול מידע נוסף.
messaging/invalid-payload	האובייקט של תוכן ההודעה לא תקין. הודעת השגיאה אמורה לכלול מידע נוסף.
messaging/invalid-data-payload-key	המטען הייעודי (payload) של הודעת הנתונים מכיל מפתח לא חוקי. למידע נוסף על מפתחות מוגבלים, קראו את מאמרי העזרה של BaseMessage.data.
messaging/payload-size-limit-exceeded	המטען הייעודי (payload) של ההודעה שצוינה חורג ממגבלות הגודל של FCM. המגבלה היא 4,096 בייטים לרוב ההודעות. להודעות שנשלחות לנושאים, המגבלה היא 2,048 בייטים. הגודל הכולל של המטען הייעודי (payload) כולל גם מפתחות וגם ערכים.
messaging/invalid-options	צוין אובייקט לא תקין של אפשרויות להודעה. הודעת השגיאה אמורה לכלול מידע נוסף.
messaging/invalid-registration-token	טוקן הרישום שצוין לא תקין. צריך לוודא שהוא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת מהרישום ב-FCM. אל תקצרו אותו ואל תוסיפו לו תווים.
messaging/registration-token-not-registered	אסימון הרישום שצוין לא רשום. יכולות להיות כמה סיבות לכך שאסימון רישום שהיה תקין בעבר לא רשום יותר, כולל: אפליקציית הלקוח ביטלה את הרישום שלה ב-FCM. אפליקציית הלקוח הוסרה אוטומטית מהרישום. זה יכול לקרות אם המשתמש מסיר את האפליקציה, או אם שירות המשוב של APNs דיווח שהאסימון של APNs לא תקין בפלטפורמות של אפל. פג התוקף של טוקן הרישום. לדוגמה, Google עשויה להחליט לרענן את אסימוני הרישום, או שתוקף האסימון של APNs במכשירי Apple פג. אפליקציית הלקוח עודכנה, אבל הגרסה החדשה לא מוגדרת לקבלת הודעות. בכל המקרים האלה, צריך להסיר את אסימון הרישום הזה ולהפסיק להשתמש בו כדי לשלוח הודעות.
messaging/invalid-package-name	ההודעה נשלחה לטוקן רישום ששם החבילה שלו לא תואם לאפשרות restrictedPackageName שצוינה.
messaging/message-rate-exceeded	קצב ההודעות ליעד מסוים גבוה מדי. צריך להפחית את מספר ההודעות שנשלחות למכשיר או לנושא הזה, ולא לנסות לשלוח שוב מיד ליעד הזה.
messaging/device-message-rate-exceeded	קצב ההודעות למכשיר מסוים גבוה מדי. צריך להפחית את מספר ההודעות שנשלחות למכשיר הזה, ולא לנסות לשלוח שוב מיד למכשיר הזה.
messaging/topics-message-rate-exceeded	קצב ההודעות למנויים בנושא מסוים גבוה מדי. צמצמו את מספר ההודעות שנשלחות לנושא הזה, ואל תנסו לשלוח שוב לנושא הזה באופן מיידי.
messaging/topics-subscription-rate-exceeded	קצב הבקשות לניהול מינויים לנושא מסוים גבוה מדי. צמצמו את מספר הבקשות שנשלחות לנושא הזה, ואל תנסו לשלוח את הבקשה שוב מיד.
messaging/too-many-topics	אסימון רישום נרשם למספר המקסימלי של נושאים ואי אפשר לרשום אותו לנושאים נוספים.
messaging/invalid-apns-credentials	לא ניתן היה לשלוח הודעה שמיועדת למכשיר Apple כי אישור ה-SSL הנדרש של APNs לא הועלה או שתוקפו פג. בודקים את התוקף של אישורי הפיתוח והייצור.
messaging/mismatched-credential	לפרטי הכניסה שמשמשים לאימות של ה-SDK הזה אין הרשאה לשלוח הודעות למכשיר שתואם לטוקן הרישום שסופק. חשוב לוודא שפרטי הכניסה ואסימון הרישום שייכים לאותו פרויקט ב-Firebase. במאמר הוספת Firebase לאפליקציה מוסבר איך לאמת את Firebase Admin SDK.
messaging/authentication-error	ה-SDK לא הצליח לבצע אימות מול השרתים של FCM. חשוב לוודא שאתם מאמתים את Firebase Admin SDK באמצעות פרטי כניסה עם ההרשאות המתאימות לשליחת הודעות FCM. במאמר הוספת Firebase לאפליקציה מוסבר איך לאמת את Firebase Admin SDK.
messaging/server-unavailable	השרת של FCM לא הצליח לעבד את הבקשה בזמן. כדאי לנסות לשלוח שוב את אותה בקשה, אבל צריך: לכבד את הכותרת Retry-After אם היא נכללת בתגובה משרת החיבור של FCM. הטמיעו השהיה מעריכית לפני ניסיון חוזר (exponential backoff) במנגנון הניסיונות החוזרים. לדוגמה, אם המתנתם שנייה אחת לפני הניסיון החוזר הראשון, המתינו לפחות שתי שניות לפני הניסיון הבא, לאחר מכן ארבע שניות, והמשיכו להגדיל את מרווח הזמן בשניות. אם שולחים כמה הודעות, צריך לעכב כל אחת מהן בנפרד בפרק זמן אקראי נוסף, כדי להימנע משליחת בקשה חדשה לכל ההודעות בו-זמנית. שולחים שגורמים לבעיות עלולים להיחסם.
messaging/internal-error	השרת של FCM נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות שוב את אותה בקשה בהתאם לדרישות שמפורטות בשורה messaging/server-unavailable הקודמת. אם השגיאה נמשכת, אפשר לדווח על הבעיה בערוץ התמיכה דיווח על באג.
messaging/unknown-error	התקבלה שגיאה לא ידועה בחיבור לשרת. כדי לקבל פרטים נוספים, אפשר לעיין בתגובת השרת הגולמית בהודעת השגיאה. אם קיבלתם את השגיאה הזו, דווחו על הודעת השגיאה המלאה בערוץ התמיכה דיווח על באג.