رموز خطأ 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 الخاصة بإصدار FCM 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/topics-subscription-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	تم عرض خطأ غير معروف في الخادم. يمكنك الاطّلاع على استجابة الخادم الأولية في رسالة الخطأ لمزيد من التفاصيل. إذا ظهر لك هذا الخطأ، يُرجى الإبلاغ عن رسالة الخطأ الكاملة في قناة الدعم الخاصة بـ الإبلاغ عن الأخطاء.