קודי שגיאה של 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 עשויה להחליט לרענן את אסימוני הרישום, או שפג התוקף של אסימון ה-APN במכשירי iOS). - אם אפליקציית הלקוח מעודכנת אבל הגרסה החדשה לא מוגדרת לקבלת הודעות. בכל המקרים האלה, צריך להסיר את אסימון הרישום הזה משרת האפליקציה ולהפסיק להשתמש בו כדי לשלוח הודעות.
SENDER_ID_MISMATCH (קוד שגיאת HTTP‏ = 403) מזהה השולח המאומת שונה ממזהה השולח של אסימון הרישום.	טוקן רישום מקושר לקבוצה מסוימת של שולחים. כשרושמים אפליקציית לקוח ל-FCM, צריך לציין אילו שולחים מורשים לשלוח הודעות. צריך להשתמש באחד ממזהי השולח האלה כששולחים הודעות לאפליקציית הלקוח. אם תעברו לשולח אחר, אסימוני הרישום הקיימים לא יפעלו.
QUOTA_EXCEEDED (קוד שגיאת HTTP‏ = 429) חריגה ממגבלת השליחה ליעד ההודעה. מוחזרת הרחבה מסוג google.rpc.QuotaFailure כדי לציין איזו מכסה חרגה.	השגיאה הזו יכולה להיגרם מחריגה מהמכסה לקצב שליחת ההודעות, מהמכסה לקצב שליחת ההודעות למכשיר או מהמכסה לקצב שליחת ההודעות לנושא. חריגה מקצב שליחת ההודעות: קצב שליחת ההודעות גבוה מדי. אתם צריכים להפחית את קצב השליחה הכולל של ההודעות. כדי לנסות לשלוח מחדש הודעות שנדחו, צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם עיכוב ראשוני של דקה אחת לפחות. Device message rate exceeded: קצב ההודעות למכשיר מסוים גבוה מדי. מגבלת קצב ההודעות למכשיר יחיד צריך להפחית את מספר ההודעות שנשלחות למכשיר הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב. Topic message rate exceeded: קצב ההודעות למנויים בנושא מסוים גבוה מדי. צריך להפחית את מספר ההודעות שנשלחות בנושא הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם השהיה ראשונית של דקה אחת לפחות לפני ניסיון השליחה הבא.
UNAVAILABLE (קוד שגיאת HTTP‏ = 503) השרת עמוס.	השרת לא הצליח לעבד את הבקשה בזמן. נסו שוב את אותה בקשה, אבל: - צריך לפעול לפי הכותרת Retry-After אם היא כלולה בתגובה משרת החיבור של FCM. - מטמיעים השהיה מעריכית לפני ניסיון חוזר (exponential backoff) במנגנון הניסיון החוזר. (לדוגמה, אם המתנתם שנייה אחת לפני הניסיון החוזר הראשון, המתינו לפחות שתי שניות לפני הניסיון הבא, אחר כך 4 שניות וכן הלאה). אם אתם שולחים כמה הודעות, כדאי להשתמש בג'יטר. מידע נוסף זמין במאמר טיפול בניסיונות חוזרים, או בלוח הבקרה של סטטוס FCM כדי לזהות אם יש שיבושים מתמשכים בשירות שמשפיעים על FCM. שולחים שגורמים לבעיות עלולים להיכנס לרשימת החסימה.
‫INTERNAL (קוד שגיאת HTTP‏ = 500) אירעה שגיאה פנימית לא ידועה.	השרת נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות שוב את אותה בקשה לפי ההצעות שמפורטות בקטע טיפול בניסיונות חוזרים או לבדוק את לוח הבקרה של סטטוס FCM. כדי לבדוק אם יש שיבושים בשירות שמשפיעים על FCM. אם השגיאה נמשכת, צריך לפנות לתמיכה של Firebase.
‫THIRD_PARTY_AUTH_ERROR (קוד שגיאת HTTP‏ = 401) אישור APNs או מפתח אימות של התראות אינטרנט לא תקין או חסר.	לא ניתן היה לשלוח הודעה שמטורגטת למכשיר iOS או לרישום של התראות אינטרנט. בודקים את התקינות של פרטי הכניסה לפיתוח ולייצור.
THIRD_PARTY_PERMISSION_DENIED (קוד שגיאת HTTP‏ = 403) לשולח אין הרשאה לשלוח לרישום שצוין.	לא ניתן היה לשלוח הודעה שמטורגטת לרישום של התראות מאתרים כי שירות ההתראות של הצד השלישי דחה את ההרשאה. מוודאים שפרטי הכניסה שלכם להתראות מאתרים תואמים לפרטי הכניסה ששימשו להרשמה.

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

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

קוד שגיאה	תיאור והשלבים לפתרון הבעיה
messaging/invalid-argument	ארגומנט לא חוקי סופק לשיטת FCM. הודעת השגיאה אמורה להכיל מידע נוסף.
messaging/invalid-recipient	הנמען של ההודעה לא תקין. הודעת השגיאה אמורה לכלול מידע נוסף.
messaging/invalid-payload	התקבל אובייקט לא תקין של מטען ייעודי (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	התקבלה שגיאה לא ידועה בחיבור לשרת. כדי לקבל פרטים נוספים, אפשר לעיין בתגובת השרת הגולמית בהודעת השגיאה. אם קיבלתם את השגיאה הזו, דווחו על הודעת השגיאה המלאה בערוץ התמיכה דיווח על באג.