رموز خطأ FCM

رموز أخطاء REST لواجهة برمجة التطبيقات HTTP v1

تحتوي استجابات أخطاء HTTP لواجهة برمجة التطبيقات HTTP v1 على رمز خطأ ورسالة خطأ وحالة الخطأ. وقد تحتوي أيضًا على مصفوفة details تتضمّن مزيدًا من التفاصيل عن الخطأ.

في ما يلي مثالان على استجابات الأخطاء:

المثال 1: استجابة خطأ من طلب بيانات من واجهة برمجة التطبيقات HTTP v1 يتضمّن قيمة غير صالحة في رسالة بيانات

{
  "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 يتضمّن رمز تسجيل غير صالح

{
  "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 الذي يتضمّن خطأً خاصًا بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase ‏(FCM)". بالنسبة إلى العديد من الأخطاء، تحتوي مصفوفة التفاصيل على المعلومات التي تحتاج إليها لتحديد المشاكل وحلّها.

يسرد الجدول التالي رموز أخطاء واجهة برمجة تطبيقات REST الخاصة بخدمة مراسلة Firebase السحابية v1 وأوصافها.

رمز الخطأ	الوصف وخطوات الحلّ
UNSPECIFIED_ERROR لا تتوفّر مزيد من المعلومات عن هذا الخطأ.	بلا.
INVALID_ARGUMENT (رمز خطأ HTTP‏ = 400) كانت مَعلمات الطلب غير صالحة. يتم عرض إضافة من النوع google.rpc.BadRequest لتحديد الحقل غير الصالح.	تشمل الأسباب المحتمَلة التسجيل غير الصالح أو اسم الحزمة غير الصالح أو الرسالة الكبيرة جدًا أو مفتاح البيانات غير الصالح أو مدّة البقاء غير الصالحة أو غير ذلك من المَعلمات غير الصالحة. التسجيل غير الصالح: تحقَّق من تنسيق رمز التسجيل الذي ترسله إلى الخادم. تأكَّد من أنّه يطابق رمز التسجيل الذي يتلقّاه تطبيق العميل من التسجيل في خدمة FCM. لا تقصّ الرمز أو تُضِف إليه أحرفًا إضافية. اسم الحزمة غير الصالح: تأكَّد من أنّ الرسالة موجَّهة إلى رمز تسجيل يتطابق اسم الحزمة الخاص به مع القيمة التي تم تمريرها في الطلب. الرسالة كبيرة جدًا: تأكَّد من أنّ الحجم الإجمالي لبيانات الحمولة المضمّنة في الرسالة لا يتجاوز حدود خدمة FCM: ‏4096 بايت لمعظم الرسائل أو 2048 بايت في حال الرسائل المرسَلة إلى المواضيع. ويشمل ذلك كلاً من المفاتيح والقيم. مفتاح البيانات غير الصالح: تأكَّد من أنّ بيانات الحمولة لا تحتوي على مفتاح (مثل from أو gcm أو أي قيمة مسبوقة بـ google) تستخدمه خدمة FCM داخليًا. يُرجى العِلم أنّ خدمة FCM تستخدم أيضًا بعض الكلمات (مثل collapse_key)، ولكنّها مسموح بها في الحمولة، وفي هذه الحالة سيتم استبدال قيمة الحمولة بقيمة FCM. مدّة البقاء غير الصالحة: تأكَّد من أنّ القيمة المستخدَمة في 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 لتحديد الحصة التي تم تجاوزها.	يمكن أن يكون سبب هذا الخطأ تجاوز الحصة المسموح بها لعدد الرسائل في الثانية أو الحصة المسموح بها لعدد الرسائل في الثانية لكل جهاز أو الحصة المسموح بها لعدد الرسائل في الثانية لكل موضوع. تجاوز الحصة المسموح بها لعدد الرسائل في الثانية: معدّل إرسال الرسائل مرتفع جدًا. عليك تقليل المعدّل الإجمالي لإرسال الرسائل. استخدِم خوارزمية الرقود الأسي الثنائي مع حد أدنى للتأخير الأولي يبلغ دقيقة واحدة لإعادة محاولة إرسال الرسائل المرفوضة. **تجاوز الحصة المسموح بها لعدد الرسائل في الثانية لكل جهاز**: معدّل إرسال الرسائل إلى جهاز معيّن مرتفع جدًا. يمكنك الاطّلاع على الحدّ الأقصى لعدد الرسائل في الثانية لجهاز واحد. قلِّل عدد الرسائل المرسَلة إلى هذا الجهاز واستخدِم خوارزمية الرقود الأسي الثنائي لإعادة محاولة الإرسال. **تجاوز الحصة المسموح بها لعدد الرسائل في الثانية لكل موضوع**: معدّل إرسال الرسائل إلى المشتركين في موضوع معيّن مرتفع جدًا. قلِّل عدد الرسائل المرسَلة لهذا الموضوع واستخدِم خوارزمية الرقود الأسي الثنائي مع حد أدنى للتأخير الأولي يبلغ دقيقة واحدة لإعادة محاولة الإرسال.
UNAVAILABLE (رمز خطأ HTTP‏ = 503) الحِمل زائد على الخادم.	تعذّر على الخادم معالجة الطلب في الوقت المناسب. أعِد إرسال الطلب نفسه، ولكن عليك: - الالتزام بعنوان `Retry-After` إذا كان مضمّنًا في الردّ من خادم اتصال FCM. - تنفيذ خوارزمية الرقود الأسي الثنائي في آلية إعادة المحاولة. (على سبيل المثال، إذا انتظرت ثانية واحدة قبل إعادة المحاولة الأولى، عليك الانتظار ثانيتَين على الأقل قبل المحاولة التالية، ثم 4 ثوانٍ وهكذا ). إذا كنت تُرسِل رسائل متعدّدة، ننصحك بتطبيق تقنية التشوّش. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة التعامل مع عمليات إعادة المحاولة، أو التحقّق من لوحة بيانات حالة FCM لتحديد ما إذا كانت هناك أي انقطاعات مستمرة في الخدمة تؤثّر في FCM. قد يتم إدراج المُرسِلين الذين يتسببون في حدوث مشاكل في القائمة المحظورة.
INTERNAL (رمز خطأ HTTP‏ = 500) حدث خطأ داخلي غير معروف.	واجه الخادم خطأً أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة إرسال الطلب نفسه باتّباع الاقتراحات الواردة في التعامل مع عمليات إعادة المحاولة أو التحقّق من لوحة بيانات حالة FCM. لتحديد ما إذا كانت هناك أي انقطاعات مستمرة في الخدمة تؤثّر في FCM. إذا استمرّ الخطأ، يُرجى التواصل مع فريق دعم Firebase.
THIRD_PARTY_AUTH_ERROR (رمز خطأ HTTP‏ = 401) كانت شهادة APNs أو مفتاح تفويض إشعارات الويب غير صالحَين أو غير متوفّرَين.	تعذّر إرسال رسالة موجَّهة إلى جهاز iOS أو تسجيل إشعارات الويب. تحقَّق من صلاحية بيانات الاعتماد الخاصة بمرحلتَي التطوير والإنتاج.

رموز أخطاء حزمة تطوير البرامج (SDK) للمشرف

يسرد الجدول التالي رموز أخطاء واجهة برمجة تطبيقات Firebase Admin FCM و أوصافها، بما في ذلك خطوات الحلّ المقترَحة.

رمز الخطأ	الوصف وخطوات الحلّ
messaging/invalid-argument	تم تقديم وسيطة غير صالحة إلى طريقة FCM. يجب أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-recipient	المستلِم المقصود للرسالة غير صالح. يجب أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-payload	تم تقديم كائن حمولة رسالة غير صالح. يجب أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-data-payload-key	تحتوي حمولة رسالة البيانات على مفتاح غير صالح. يمكنك الاطّلاع على المستندات المرجعية لـ DataMessagePayload لمعرفة المفاتيح المحظورة.
messaging/payload-size-limit-exceeded	تتجاوز حمولة الرسالة المقدَّمة حدود الحجم في خدمة FCM. الحدّ الأقصى هو 4096 بايت لمعظم الرسائل. بالنسبة إلى الرسائل المرسَلة إلى المواضيع، الحدّ الأقصى هو 2048 بايت. يشمل الحجم الإجمالي للحمولة كلاً من المفاتيح والقيم.
messaging/invalid-options	تم تقديم كائن خيارات رسالة غير صالح. يجب أن تحتوي رسالة الخطأ على معلومات إضافية.
messaging/invalid-registration-token	تم تقديم رمز تسجيل غير صالح. تأكَّد من أنّه يطابق رمز التسجيل الذي يتلقّاه تطبيق العميل من التسجيل في خدمة FCM. لا تقصّ الرمز أو تُضِف إليه أحرفًا إضافية.
messaging/registration-token-not-registered	رمز التسجيل المقدَّم غير مسجَّل. يمكن إلغاء تسجيل رمز تسجيل صالح سابقًا لعدّة أسباب، بما في ذلك: ألغى تطبيق العميل تسجيله من FCM. تم إلغاء تسجيل تطبيق العميل تلقائيًا. يمكن أن يحدث ذلك إذا ألغى المستخدم تثبيت التطبيق أو، على منصات Apple، إذا أبلغت خدمة ملاحظات 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 SDKs.
messaging/authentication-error	تعذّر على حزمة تطوير البرامج (SDK) المصادقة على خوادم FCM. تأكَّد من المصادقة على Firebase Admin SDK باستخدام بيانات اعتماد تملك الأذونات المناسبة لإرسال FCM رسائل. يمكنك الاطّلاع على مقالة إضافة Firebase إلى تطبيقك للحصول على مستندات حول كيفية المصادقة على Firebase Admin SDKs.
messaging/server-unavailable	تعذّر على خادم FCM معالجة الطلب في الوقت المناسب. عليك إعادة إرسال الطلب نفسه، ولكن يجب: الالتزام بعنوان Retry-After إذا كان مضمّنًا في الردّ من خادم اتصال FCM. تنفيذ خوارزمية الرقود الأسي الثنائي في آلية إعادة المحاولة. على سبيل المثال، إذا انتظرت ثانية واحدة قبل إعادة المحاولة الأولى، عليك الانتظار ثانيتَين على الأقل قبل المحاولة التالية، ثم أربع ثوانٍ، والاستمرار في زيادة الفاصل الزمني بالثواني. إذا كنت تُرسِل رسائل متعدّدة، عليك تأخير كل رسالة بشكل مستقل بمقدار عشوائي إضافي لتجنُّب إصدار طلب جديد لجميع الرسائل في الوقت نفسه. قد يتم إدراج المُرسِلين الذين يتسببون في حدوث مشاكل في القائمة المحظورة.
messaging/internal-error	واجه خادم FCM خطأً أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة إرسال الطلب نفسه باتّباع المتطلبات المُدرَجة في صف messaging/server-unavailable السابق. إذا استمرّ الخطأ، يُرجى الإبلاغ عن المشكلة في قناة دعم "الإبلاغ عن الأخطاء".
messaging/unknown-error	تم عرض خطأ غير معروف في الخادم. يمكنك الاطّلاع على استجابة الخادم الأولية في رسالة الخطأ لمزيد من التفاصيل. إذا ظهر لك هذا الخطأ، يُرجى الإبلاغ عن رسالة الخطأ الكاملة في قناة دعم الإبلاغ عن الأخطاء.