رموز خطأ FCM

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

تحتوي استجابات أخطاء 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: ردّ يتضمّن خطأ من طلب بيانات من الإصدار 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 API لخدمة مراسلة Firebase السحابية وأوصافها.

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

رموز أخطاء مدير SDK

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

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