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