رموز خطأ FCM

رموز أخطاء REST لواجهة برمجة التطبيقات HTTP الإصدار 1

تحتوي ردود أخطاء HTTP لواجهة برمجة التطبيقات HTTP الإصدار 1 على رمز خطأ ورسالة خطأ وحالة خطأ. قد تحتوي أيضًا على مصفوفة 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 الإصدار 1 يتضمّن رمز تسجيل غير صالح

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

يسرد الجدول التالي رموز الأخطاء في واجهة برمجة التطبيقات REST لإصدار 1 من FCM وأوصافها.

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

رموز أخطاء حزمة SDK للمشرف

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

رمز الخطأ	الوصف وخطوات الحل
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. تم إلغاء تسجيل تطبيق العميل تلقائيًا. يمكن أن يحدث ذلك إذا ألغى المستخدم تثبيت التطبيق أو إذا أبلغت خدمة APNs Feedback عن أنّ رمز APNs غير صالح على منصات Apple. انتهت صلاحية رمز التسجيل. على سبيل المثال، قد تقرّر 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	تم عرض خطأ غير معروف في الخادم. يمكنك الاطّلاع على الردّ الأولي من الخادم في رسالة الخطأ للحصول على مزيد من التفاصيل. إذا ظهرت لك رسالة الخطأ هذه، يُرجى إبلاغنا بها كاملةً من خلال قناة الدعم تقرير الأخطاء.