رموز خطأ FCM

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

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

في ما يلي نموذجان لردود تتضمّن أخطاء:

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

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

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

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

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