رموز خطأ 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 السحابية. بالنسبة إلى العديد من الأخطاء، تحتوي مصفوفة التفاصيل على المعلومات التي تحتاج إليها لتحديد المشاكل وحلّها.

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

رمز الخطأ	الوصف وخطوات الحلّ
UNSPECIFIED_ERROR لا تتوفّر معلومات إضافية عن هذا الخطأ.	بلا.
INVALID_ARGUMENT (رمز خطأ HTTP‏ = 400) كانت مَعلمات الطلب غير صالحة. يتم عرض إضافة من النوع google.rpc.BadRequest لتحديد الحقل غير الصالح.	تشمل الأسباب المحتمَلة التسجيل غير الصالح أو اسم الحزمة غير الصالح أو الرسالة الكبيرة جدًا أو مفتاح البيانات غير الصالح أو مدة البقاء غير الصالحة أو غير ذلك من المَعلمات غير الصالحة. التسجيل غير الصالح: تحقَّق من تنسيق رمز التسجيل الذي ترسله إلى الخادم. تأكَّد من أنّه يطابق رمز التسجيل الذي يتلقّاه تطبيق العميل من التسجيل في خدمة مراسلة Firebase السحابية. لا تقصّ الرمز أو تُضِف إليه أحرفًا إضافية. اسم الحزمة غير الصالح: تأكَّد من أنّ الرسالة موجَّهة إلى رمز تسجيل يتطابق اسم الحزمة الخاص به مع القيمة التي تم تمريرها في الطلب. الرسالة الكبيرة جدًا: تأكَّد من أنّ الحجم الإجمالي لبيانات الحمولة المُضمَّنة في الرسالة لا يتجاوز الحدود القصوى لمراسلة Firebase السحابية: 4096 بايت لمعظم الرسائل، أو 2048 بايت في حال الرسائل المرسَلة إلى المواضيع. ويشمل ذلك كلاً من المفاتيح والقيم. مفتاح البيانات غير الصالح: تأكَّد من أنّ بيانات الحمولة لا تحتوي على مفتاح (مثل from أو GCM أو أي قيمة مسبوقة بـ google) تستخدمه مراسلة Firebase السحابية داخليًا. يُرجى العِلم أنّ خدمة المراسلة عبر السحابة الإلكترونية من Firebase تستخدم أيضًا بعض الكلمات (مثل collapse_key)، ولكن يُسمح بها في الحمولة، وفي هذه الحالة سيتم استبدال قيمة الحمولة بقيمة خدمة المراسلة عبر السحابة الإلكترونية من Firebase. مدة البقاء غير الصالحة: تأكَّد من أنّ القيمة المستخدَمة في ttl هي عدد صحيح يمثّل مدة بالثواني تتراوح بين 0 و2,419,200 (4 أسابيع). المَعلمات غير الصالحة: تأكَّد من أنّ المَعلمات المقدَّمة لها الاسم والنوع الصحيحان.
UNREGISTERED (رمز خطأ HTTP‏ = 404) تم إلغاء تسجيل مثيل التطبيق من خدمة المراسلة عبر السحابة الإلكترونية من Firebase. يعني ذلك عادةً أنّ الرمز المستخدَم لم يعُد صالحًا ويجب استخدام رمز جديد.	يمكن أن يكون سبب هذا الخطأ عدم توفّر رموز التسجيل أو إلغاء تسجيل الرموز. التسجيل غير المتوفّر: إذا كان هدف الرسالة قيمة token، تأكَّد من أنّ الطلب يحتوي على رمز تسجيل. غير مسجَّل: قد يتوقف رمز التسجيل الحالي عن أن يكون صالحًا في عدد من السيناريوهات، بما في ذلك: - إذا ألغى تطبيق العميل تسجيله من مراسلة Firebase السحابية. - إذا تم إلغاء تسجيل تطبيق العميل تلقائيًا، وهو ما يمكن أن يحدث إذا ألغى المستخدم تثبيت التطبيق. على سبيل المثال، على أجهزة iOS، إذا أبلغت خدمة ملاحظات APNs عن أنّ رمز APNs غير صالح. - إذا انتهت صلاحية رمز التسجيل (على سبيل المثال، قد تقرّر Google إعادة تحميل رموز التسجيل، أو انتهت صلاحية رمز APNs لأجهزة iOS). - إذا تم تحديث تطبيق العميل ولكن لم يتم ضبط الإصدار الجديد لتلقّي الرسائل. في كل هذه الحالات، أزِل رمز التسجيل هذا من خادم التطبيق وتوقَّف عن استخدامه لإرسال الرسائل.
SENDER_ID_MISMATCH (رمز خطأ HTTP‏ = 403) يختلف معرّف المُرسِل الذي تم التحقّق منه عن معرّف المُرسِل لرمز التسجيل.	يرتبط رمز التسجيل بمجموعة معيّنة من المُرسِلين. عندما يسجّل تطبيق العميل في خدمة مراسلة Firebase السحابية، يجب أن يحدّد المُرسِلين المسموح لهم بإرسال الرسائل. عليك استخدام أحد معرّفات المُرسِلين هذه عند إرسال الرسائل إلى تطبيق العميل. وإذا بدّلت إلى مُرسِل مختلف، لن تعمل رموز التسجيل الحالية.
QUOTA_EXCEEDED (رمز خطأ HTTP‏ = 429) تم تجاوز عدد الرسائل المسموح بإرسالها إلى هدف الرسالة. يتم عرض إضافة من النوع google.rpc.QuotaFailure لتحديد الحصة التي تم تجاوزها.	يمكن أن يكون سبب هذا الخطأ تجاوز الحصة المحدّدة لمعدّل الرسائل أو الحصة المحدّدة لمعدّل الرسائل على الجهاز أو الحصة المحدّدة لمعدّل الرسائل إلى المواضيع. **تجاوز الحصة المحدّدة لمعدّل الرسائل**: معدّل إرسال الرسائل مرتفع جدًا. عليك خفض المعدّل الإجمالي لإرسال الرسائل. استخدِم خوارزمية الرقود الأسي الثنائي مع حد أدنى للتأخير الأولي يبلغ دقيقة واحدة لإعادة محاولة إرسال الرسائل المرفوضة. تجاوز الحصة المحدّدة لمعدّل الرسائل على الجهاز: معدّل إرسال الرسائل إلى جهاز معيّن مرتفع جدًا. يمكنك الاطّلاع على الحدّ الأقصى لمعدّل الرسائل إلى جهاز واحد. قلِّل عدد الرسائل المرسَلة إلى هذا الجهاز واستخدِم خوارزمية الرقود الأسي الثنائي لإعادة محاولة الإرسال. تجاوز الحصة المحدّدة لمعدّل الرسائل إلى المواضيع: معدّل إرسال الرسائل إلى المشتركين في موضوع معيّن مرتفع جدًا. قلِّل عدد الرسائل المرسَلة لهذا الموضوع واستخدِم خوارزمية الرقود الأسي الثنائي مع حد أدنى للتأخير الأولي يبلغ دقيقة واحدة لإعادة محاولة الإرسال.
UNAVAILABLE (رمز خطأ HTTP‏ = 503) الخادم مثقل.	تعذّر على الخادم معالجة الطلب في الوقت المناسب. أعِد محاولة إرسال الطلب نفسه، ولكن عليك: - الالتزام بالعنوان Retry-After إذا كان مُضمَّنًا في الردّ من خادم اتصال خدمة مراسلة Firebase السحابية. - تنفيذ خوارزمية الرقود الأسي الثنائي في آلية إعادة المحاولة. (على سبيل المثال، إذا انتظرت ثانية واحدة قبل إعادة المحاولة الأولى، انتظِر ثانيتَين على الأقل قبل المحاولة التالية، ثم 4 ثوانٍ وهكذا ). إذا كنت تُرسِل رسائل متعدّدة، ننصحك بتطبيق تقنية التشوّش. لمزيد من المعلومات، يمكنك الاطّلاع على مقالة التعامل مع عمليات إعادة المحاولة، أو التحقّق من لوحة بيانات حالة خدمة المراسلة عبر السحابة الإلكترونية من Firebase لتحديد ما إذا كانت هناك أي انقطاعات حالية في الخدمة تؤثّر في خدمة المراسلة عبر السحابة الإلكترونية من Firebase. قد يتم إدراج المُرسِلين الذين يسبّبون مشاكل في القائمة المحظورة.
INTERNAL (رمز خطأ HTTP‏ = 500) حدث خطأ داخلي غير معروف.	حدث خطأ في الخادم أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة إرسال الطلب نفسه باتّباع الاقتراحات الواردة في التعامل مع عمليات إعادة المحاولة أو التحقّق من لوحة البيانات الخاصة بحالة خدمة مراسلة Firebase السحابية. لتحديد ما إذا كانت هناك أي انقطاعات حالية في الخدمة تؤثّر في مراسلة Firebase السحابية. إذا استمر الخطأ، يُرجى التواصل مع فريق دعم 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	تتجاوز حمولة الرسالة المقدَّمة الحدود القصوى لحجم الرسالة في خدمة المراسلة عبر السحابة الإلكترونية من Firebase 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	تم عرض خطأ غير معروف في الخادم. يمكنك الاطّلاع على استجابة الخادم الأولية في رسالة الخطأ لمزيد من التفاصيل. إذا ظهر لك هذا الخطأ، يُرجى الإبلاغ عن رسالة الخطأ الكاملة في قناة دعم الإبلاغ عن الأخطاء.