קודי שגיאה של 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: תגובת שגיאה מבקשת API של HTTP v1 עם אסימון רישום לא תקין

{
  "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"
      }
    ]
   }
}

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

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

קוד שגיאה	תיאור ושלבים לפתרון
UNSPECIFIED_ERROR אין מידע נוסף על השגיאה הזו.	אין.
‫INVALID_ARGUMENT (קוד שגיאת HTTP‏ = 400) הפרמטרים של הבקשה לא תקינים. מוחזרת תוסף מסוג google.rpc.BadRequest כדי לציין איזה שדה לא תקין.	הסיבות האפשריות כוללות רישום לא תקין, שם חבילה לא תקין, הודעה גדולה מדי, מפתח נתונים לא תקין, ערך TTL לא תקין או פרמטרים לא תקינים אחרים. רישום לא תקין: צריך לבדוק את הפורמט של טוקן הרישום שמועבר לשרת. חשוב לוודא שהערך זהה לטוקן הרישום שאפליקציית הלקוח מקבלת אחרי הרישום ל-FCM. אל תקצרו את האסימון ואל תוסיפו לו תווים. שם חבילה לא חוקי: מוודאים שההודעה מיועדת לטוקן רישום ששם החבילה שלו תואם לערך שהועבר בבקשה. ההודעה גדולה מדי: צריך לוודא שהגודל הכולל של נתוני המטען הייעודי (payload) שכלולים בהודעה לא חורג מהמגבלות של 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: If the message's target is a token value, check that the request contains a registration token. Not registered: יכול להיות שאסימון רישום קיים יפסיק להיות תקף בכמה תרחישים, כולל: – אם אפליקציית הלקוח מבטלת את הרישום ב-FCM. – אם האפליקציה של הלקוח מבטלת את הרישום באופן אוטומטי, מה שיכול לקרות אם המשתמש מסיר את האפליקציה. לדוגמה, ב-iOS, אם שירות המשוב של APNs דיווח שאסימון ה-APNs לא תקין. – אם פג התוקף של אסימון הרישום (לדוגמה, יכול להיות ש-Google תחליט לרענן את אסימוני הרישום, או שפג התוקף של אסימון ה-APNs במכשירי iOS). – אם אפליקציית הלקוח עודכנה אבל הגרסה החדשה לא מוגדרת לקבלת הודעות. בכל המקרים האלה, צריך להסיר את אסימון הרישום הזה משרת האפליקציה ולהפסיק להשתמש בו לשליחת הודעות.
‫SENDER_ID_MISMATCH (קוד שגיאת HTTP‏ = 403) מזהה השולח שאומת שונה ממזהה השולח של טוקן הרישום.	אסימון רישום מקושר לקבוצה מסוימת של שולחים. כשמבצעים רישום של אפליקציית לקוח ל-FCM, צריך לציין אילו שולחים מורשים לשלוח הודעות. כששולחים הודעות לאפליקציית הלקוח, צריך להשתמש באחד ממזהי השולח האלה. אם עוברים לשולח אחר, אסימוני הרישום הקיימים לא יפעלו.
QUOTA_EXCEEDED (קוד שגיאת HTTP‏ = 429) חרגת ממגבלת השליחה של יעד ההודעה. מוחזר תוסף מסוג google.rpc.QuotaFailure כדי לציין את המכסה שנחצתה.	השגיאה הזו יכולה להיגרם אם חרגתם ממכסת קצב שליחת ההודעות, ממכסת קצב שליחת ההודעות למכשיר או ממכסת קצב שליחת ההודעות לנושא. חריגה מקצב ההודעות: קצב השליחה של ההודעות גבוה מדי. צריך להקטין את השיעור הכולל של שליחת ההודעות. כדי לנסות לשלוח שוב הודעות שנדחו, צריך להשתמש בהשהיה מעריכית לפני ניסיון חוזר עם עיכוב ראשוני מינימלי של דקה אחת. חריגה מקצב ההודעות למכשיר: קצב ההודעות למכשיר מסוים גבוה מדי. מידע על מגבלת קצב שליחת ההודעות למכשיר בודד צריך להקטין את מספר ההודעות שנשלחות למכשיר הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר כדי לנסות לשלוח שוב. חריגה מקצב ההודעות בנושא: קצב ההודעות למנויים בנושא מסוים גבוה מדי. צריך להקטין את מספר ההודעות שנשלחות בנושא הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) עם עיכוב התחלתי מינימלי של דקה אחת כדי לנסות לשלוח שוב.
‫UNAVAILABLE (קוד שגיאת HTTP‏ = 503) השרת עמוס מדי.	השרת לא הצליח לעבד את הבקשה בזמן. מנסים לשלוח שוב את אותה בקשה, אבל צריך: – לפעול בהתאם לכותרת Retry-After אם היא כלולה בתגובה משרת החיבור של FCM. – הטמעת השהיה מעריכית לפני ניסיון חוזר במנגנון הניסיון החוזר. (לדוגמה, אם חיכיתם שנייה אחת לפני הניסיון החוזר הראשון, צריך לחכות לפחות שתי שניות לפני הניסיון הבא, ואז 4 שניות וכן הלאה). אם אתם שולחים כמה הודעות, כדאי להשתמש בשיטת הוספת שינויים קלים לזמני השליחה. מידע נוסף זמין במאמר טיפול בניסיונות חוזרים. אפשר גם לבדוק ב לוח הבקרה של סטטוס FCM אם יש שיבושים בשירות שמשפיעים על FCM. שולחים שגורמים לבעיות עלולים להיכנס לרשימת החסימה.
‫INTERNAL (קוד שגיאת HTTP‏ = 500) אירעה שגיאה פנימית לא ידועה.	השרת נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות לשלוח שוב את אותה בקשה לפי ההצעות שבמאמר טיפול בניסיונות חוזרים או לבדוק את לוח הבקרה של סטטוס FCM. כדי לזהות אם יש שיבושים בשירות שמשפיעים על FCM. אם השגיאה נמשכת, צריך לפנות לתמיכה של Firebase.
THIRD_PARTY_AUTH_ERROR (קוד שגיאת HTTP‏ = 401) אישור APNs או מפתח אימות של הודעות פוש לאינטרנט לא תקין או חסר.	לא ניתן לשלוח הודעה שמיועדת למכשיר iOS או לרישום של הודעת פוש באינטרנט. בודקים את התוקף של פרטי הכניסה של סביבת הפיתוח וסביבת הייצור.

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