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

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

תגובות שגיאה של HTTP ב-API של HTTP v1 מכילות קוד שגיאה, הודעת שגיאה וסטטוס שגיאה. יכול להיות שהם יכילו גם מערך 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 הוא 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. אל תחתוך את האסימון ואל תוסיף תווים.
שם החבילה לא חוקי: מוודאים שההודעה מיועדת לטוקן רישום ששם החבילה שלו זהה לערך שמועבר בבקשה.
ההודעה גדולה מדי: צריך לוודא שהגודל הכולל של נתוני המטען הייעודי שנכללים בהודעה לא חורג מהמגבלות של FCM: ‏ 4,096 בייטים לרוב ההודעות, או 2,048 בייטים במקרה של הודעות לנושאים. ההגדרה הזו כוללת גם את המפתחות וגם את הערכים.
מפתח נתונים לא תקין: צריך לוודא שנתוני מטען הייעודי לא מכילים מפתח (כמו from,‏ gcm או כל ערך עם הקידומת google) שמשמש באופן פנימי את FCM. שימו לב: חלק מהמילים (כמו collapse_key) משמשות גם את FCM, אבל מותר להשתמש בהן במטען הייעודי (payload). במקרה כזה, הערך של המטען הייעודי יוחלף בערך של FCM.
TTL לא תקין: צריך לוודא שהערך שמשמש ל-TTL הוא מספר שלם שמייצג משך זמן בשניות בין 0 ל-2,419,200 (4 שבועות).
פרמטרים לא תקינים: צריך לוודא שהפרמטרים שצוינו הם מהסוג הנכון ושהשם שלהם נכון.
‫UNREGISTERED (קוד שגיאת HTTP‏ = 404) ביטול הרישום של מופע האפליקציה מ-FCM. בדרך כלל זה אומר שהטוקן שבו נעשה שימוש כבר לא תקף וצריך להשתמש בטוקן חדש. השגיאה הזו יכולה להיגרם מטוקנים חסרים של רישום או מטוקנים לא רשומים.
Missing Registration: אם היעד של ההודעה הוא ערך token, צריך לוודא שהבקשה מכילה טוקן רישום.
לא רשום: יכול להיות שאסימון רישום קיים יפסיק להיות תקף בכמה תרחישים, כולל:
– אם אפליקציית הלקוח מבטל את הרישום ב-FCM.
– אם האפליקציה של הלקוח מבטלת את הרישום שלה באופן אוטומטי, מה שיכול לקרות אם המשתמש מסיר את ההתקנה של האפליקציה. לדוגמה, ב-iOS, אם שירות המשוב של APNs דיווח שאסימון ה-APNs לא תקין.
– אם פג התוקף של אסימון ההרשמה (לדוגמה, יכול להיות ש-Google תחליט לרענן את אסימוני ההרשמה, או שפג התוקף של אסימון ה-APNs במכשירי iOS).
– אם אפליקציית הלקוח עודכנה אבל הגרסה החדשה לא מוגדרת לקבלת הודעות.
בכל המקרים האלה, צריך להסיר את אסימון הרישום הזה משרת האפליקציה ולהפסיק להשתמש בו לשליחת הודעות.
‫SENDER_ID_MISMATCH (קוד שגיאת HTTP‏ = 403) מזהה השולח המאומת שונה ממזהה השולח של טוקן הרישום. אסימון רישום מקושר לקבוצה מסוימת של שולחים. כשמבצעים רישום של אפליקציית לקוח ל-FCM, צריך לציין אילו שולחים מורשים לשלוח הודעות. צריך להשתמש באחד ממזהי השולח האלה כששולחים הודעות לאפליקציית הלקוח. אם עוברים לשולח אחר, אסימוני הרישום הקיימים לא יפעלו.
‫QUOTA_EXCEEDED (קוד שגיאת HTTP‏ = 429) חריגה ממגבלת השליחה של יעד ההודעה. מוחזרת הרחבה מסוג google.rpc.QuotaFailure כדי לציין את המכסה שהייתה חריגה ממנה. השגיאה הזו יכולה להיגרם אם חרגתם ממכסת קצב שליחת ההודעות, ממכסת קצב שליחת ההודעות מהמכשיר או ממכסת קצב שליחת ההודעות לנושא.
חריגה מקצב שליחת ההודעות: קצב שליחת ההודעות גבוה מדי. צריך להקטין את השיעור הכולל של שליחת ההודעות. כדי לנסות לשלוח שוב הודעות שנדחו, צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר עם עיכוב ראשוני מינימלי של דקה אחת.
חרגת מהמגבלה על קצב העברת ההודעות למכשיר: קצב העברת ההודעות למכשיר מסוים גבוה מדי. מידע על מגבלת קצב שליחת ההודעות למכשיר בודד צריך להקטין את מספר ההודעות שנשלחות למכשיר הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר כדי לנסות לשלוח שוב.
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 או רישום של הודעת פוש באינטרנט. בודקים את התוקף של פרטי הכניסה בסביבות הפיתוח והייצור.

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

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

קוד שגיאה תיאור ושלבי פתרון
messaging/invalid-argument סופק ארגומנט לא תקין לשיטה FCM. הודעת השגיאה אמורה לכלול מידע נוסף.
messaging/invalid-recipient הנמען של ההודעה לא תקין. הודעת השגיאה אמורה לכלול מידע נוסף.
messaging/invalid-payload סופק אובייקט מטען (payload) של הודעה לא תקין. הודעת השגיאה אמורה לכלול מידע נוסף.
messaging/invalid-data-payload-key המטען הייעודי (payload) של הודעת הנתונים מכיל מפתח לא תקין. מידע נוסף על מפתחות מוגבלים זמין במאמרי העזרה של DataMessagePayload.
messaging/payload-size-limit-exceeded המטען הייעודי (payload) של ההודעה שצוין חורג ממגבלות הגודל של FCM. המגבלה היא 4,096 בייט לרוב ההודעות. להודעות שנשלחות לנושאים, המגבלה היא 2,048 בייט. הגודל הכולל של מטען הייעודי כולל גם את המפתחות וגם את הערכים.
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, צריך להתייחס אליה.
  • הטמעת השהיה מעריכית לפני ניסיון חוזר במנגנון הניסיון החוזר. לדוגמה, אם חיכיתם שנייה אחת לפני הניסיון הראשון, צריך לחכות לפחות שתי שניות לפני הניסיון הבא, ואז ארבע שניות, ולהמשיך להגדיל את מרווח הזמן. אם אתם שולחים כמה הודעות, כדאי להשהות כל אחת מהן בנפרד למשך זמן אקראי נוסף, כדי למנוע שליחה של בקשה חדשה לכל ההודעות בו-זמנית.
שולחים שגורמים לבעיות עלולים להיכנס לרשימת החסימה.
messaging/internal-error השרת FCM נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות לשלוח שוב את אותה בקשה בהתאם לדרישות שצוינו בשורה messaging/server-unavailable למעלה. אם השגיאה נמשכת, אפשר לדווח על הבעיה בערוץ התמיכה שלנו בנושא דיווח על באגים.
messaging/unknown-error הוחזרה שגיאה לא ידועה בחיבור לשרת. פרטים נוספים מופיעים בהודעת השגיאה בתגובה הגולמית של השרת. אם השגיאה הזו מופיעה, צריך לדווח על הודעת השגיאה המלאה בערוץ התמיכה שלנו בנושא דיווח על באגים.