کدهای خطای FCM

کدهای خطای REST برای HTTP v1 API

پاسخ‌های خطای HTTP برای HTTP v1 API حاوی کد خطا، پیام خطا، و وضعیت خطا است. همچنین ممکن است حاوی آرایه details با جزئیات بیشتر درباره خطا باشند.

در اینجا دو نمونه پاسخ خطا آورده شده است:

مثال ۱: پاسخ خطا از درخواست 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"
          }
        ]
      }
    ]
  }
}

مثال ۲: پاسخ خطا از درخواست HTTP v1 API با کد ثبت نامعتبر

{
  "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 دارد. برای بسیاری از خطاها، آرایه جزئیات حاوی اطلاعاتی است که برای اشکال‌زدایی و یافتن راه‌حل به آن نیاز دارید.

جدول زیر کدهای خطای FCM v1 REST API و شرح آن‌ها را فهرست می‌کند.

کد خطا	شرح و مراحل حل‌وفصل
UNSPECIFIED_ERROR اطلاعات بیشتری درباره این خطا دردسترس نیست.	هیچ‌یک.
INVALID_ARGUMENT (کد خطای HTTP‏ = ۴۰۰) پارامترهای درخواست نامعتبر بود. افزونه‌ای از نوع google.rpc.BadRequest برگردانده می‌شود تا مشخص کند کدام فیلد نامعتبر بوده است.	دلایل احتمالی شامل ثبت نامعتبر، نام بسته نامعتبر، پیام بسیار بزرگ، کلید داده نامعتبر، TTL نامعتبر، یا سایر پارامترهای نامعتبر است. ثبت نامعتبر: قالب کد ثبت را که به سرور ارسال می‌کنید بررسی کنید. مطمئن شوید که با کد ثبت دریافتی برنامه کارخواه از ثبت با FCM مطابقت داشته باشد. توکن را کوتاه نکنید یا نویسه اضافی به آن اضافه نکنید. نام بسته نامعتبر است: مطمئن شوید پیام به یک کد ثبت ارسال شده باشد که نام بسته آن با مقدار ارسال‌شده در درخواست مطابقت داشته باشد. پیام خیلی بزرگ است: بررسی کنید که اندازه کل داده‌های پایه‌بار موجود در پیام از محدودیت‌های FCM فراتر نرود: ۴۰۹۶ بایت برای اکثر پیام‌ها، یا ۲۰۴۸ بایت در مورد پیام‌های ارسال‌شده به موضوعات. این شامل کلیدها و مقادیر می‌شود. کلید داده نامعتبر: بررسی کنید که داده‌های بار مفید حاوی کلیدی (مانند from، یا gcm، یا هر مقداری با پیشوند google) نباشد که به‌طور داخلی توسط FCM استفاده می‌شود. توجه داشته باشید که برخی‌از کلمات (مانند collapse_key) نیز توسط FCM استفاده می‌شوند اما در بار داده مجاز هستند، که در این صورت مقدار بار داده توسط مقدار FCM لغو خواهد شد. زمان بقای نامعتبر: بررسی کنید که مقدار استفاده‌شده در زمان بقا عدد صحیحی باشد که مدت‌زمان را به ثانیه بین ۰ تا ۲٬۴۱۹٬۲۰۰ (۴ هفته) نشان می‌دهد. پارامترهای نامعتبر: بررسی کنید که پارامترهای ارائه‌شده نام و نوع درستی داشته باشند.
UNREGISTERED (کد خطای HTTP = ‏ ۴۰۴) ثبت نمونه برنامه از FCM لغو شد. این معمولاً به این معنی است که توکن استفاده‌شده دیگر معتبر نیست و باید از توکن جدیدی استفاده شود.	این خطا می‌تواند به‌دلیل نبودن کدهای ثبت‌نام یا کدهای ثبت‌نشده باشد. ثبت‌نام وجود ندارد: اگر هدف پیام مقدار token است، بررسی کنید که درخواست حاوی یک کد ثبت‌نام باشد. ثبت‌نشده: ممکن است در چند سناریو، توکن ثبت موجود دیگر معتبر نباشد، ازجمله: - اگر برنامه کارخواه ثبت‌نام خود را در FCM لغو کند. - اگر ثبت‌نام برنامه کارخواه به‌طور خودکار لغو شود، که ممکن است درصورت حذف نصب برنامه توسط کاربر اتفاق بیفتد. برای مثال، در iOS، اگر «سرویس بازخورد APN» توکن APN را نامعتبر گزارش کرده باشد. - اگر کد ثبت منقضی شود (برای مثال، Google ممکن است تصمیم بگیرد کدهای ثبت را بازآوری کند، یا کد APN برای دستگاه‌های iOS منقضی شده باشد). - اگر برنامه کارخواه به‌روز شده باشد اما نسخه جدید برای دریافت پیام پیکربندی نشده باشد. برای همه این موارد، این کد ثبت را از سرور برنامه بردارید و دیگر از آن برای ارسال پیام استفاده نکنید.
SENDER_ID_MISMATCH (کد خطای HTTP‏ = ۴۰۳) شناسه فرستنده اصالت‌سنجی‌شده با شناسه فرستنده برای کد ثبت متفاوت است.	یک توکن ثبت به گروه خاصی از فرستندگان گره خورده است. وقتی برنامه مشتری برای FCM ثبت‌نام می‌کند، باید مشخص کند کدام فرستندگان مجاز به ارسال پیام هستند. هنگام ارسال پیام به برنامه کارخواه، باید از یکی از آن شناسه‌های فرستنده استفاده کنید. اگر به فرستنده دیگری بروید، کدهای ثبت موجود کار نخواهند کرد.
QUOTA_EXCEEDED (کد خطای HTTP = ‏۴۲۹) از حد ارسال برای هدف پیام فراتر رفته است. افزونه‌ای از نوع google.rpc.QuotaFailure برگردانده می‌شود تا مشخص کند از کدام سهمیه فراتر رفته‌اید.	این خطا می‌تواند به‌دلیل فراتر رفتن از سهمیه نرخ پیام، فراتر رفتن از سهمیه نرخ پیام دستگاه، یا فراتر رفتن از سهمیه نرخ پیام موضوع باشد. از نرخ پیام فراتر رفته است: نرخ ارسال پیام‌ها بسیار بالا است. باید نرخ کلی ارسال پیام را کاهش دهید. برای امتحان مجدد پیام‌های ردشده، از عقب‌نشینی نمایی با حداقل تأخیر اولیه ۱ دقیقه استفاده کنید. نرخ پیام دستگاه فراتر رفته است: نرخ پیام‌ها به دستگاهی خاص بسیار بالا است. محدودیت نرخ پیام برای یک دستگاهرا ببینید. تعداد پیام‌های ارسالی به این دستگاه را کاهش دهید و برای ارسال مجدد از عقب‌نشینی نمایی استفاده کنید. نرخ پیام موضوع فراتر رفته است: نرخ پیام‌ها به مشترکین یک موضوع خاص بسیار بالا است. تعداد پیام‌های ارسال‌شده برای این موضوع را کاهش دهید و از عقب‌نشینی نمایی با حداقل تأخیر اولیه ۱ دقیقه برای ارسال مجدد استفاده کنید.
UNAVAILABLE (کد خطای HTTP‏ = ۵۰۳) سرور اضافه‌بار دارد.	سرور نتوانست درخواست را به‌موقع پردازش کند. همان درخواست را دوباره امتحان کنید، اما باید: - اگر سرصفحه Retry-After در پاسخ FCM Connection Server گنجانده شده است، آن را رعایت کنید. - عقب‌گرد نمایی را در سازوکار تکرار مجدد خود پیاده‌سازی کنید. (مثلاً اگر قبل‌از اولین تلاش مجدد یک ثانیه صبر کردید، قبل‌از تلاش بعدی حداقل دو ثانیه صبر کنید، سپس ۴ ثانیه و به همین ترتیب). اگر چندین پیام ارسال می‌کنید، لرزش را اعمال کنید. برای اطلاعات بیشتر، مدیریت تلاش‌های مجددرا ببینید، یا داشبورد وضعیت FCM را بررسی کنید تا ببینید آیا اختلالات سرویس درحال انجام وجود دارد که بر FCM تأثیر بگذارد. فرستندگانی که مشکل ایجاد می‌کنند ممکن است در فهرست رد قرار بگیرند.
INTERNAL (کد خطای HTTP‏ = ۵۰۰) خطای داخلی نامشخصی رخ داد.	سرور هنگام پردازش درخواست با خطایی مواجه شد. می‌توانید همان درخواست را با دنبال کردن پیشنهادهای موجود در مدیریت تلاش‌های مجدد یا بررسی داشبورد وضعیت FCM دوباره امتحان کنید. تا ببینید آیا اختلال سرویس جاری‌ای وجود دارد که بر FCM تأثیر بگذارد. اگر خطا برطرف نشد، لطفاً با پشتیبانی Firebase تماس بگیرید.
THIRD_PARTY_AUTH_ERROR (کد خطای HTTP = ‏ ۴۰۱) گواهی APNs یا کلید اصالت‌سنجی ارسال وب نامعتبر یا مفقود بود.	پیامی که برای دستگاه iOS یا ثبت ارسال وب هدف‌یابی شده بود ارسال نشد. اعتبار اعتبارنامه‌های توسعه و تولیدتان را بررسی کنید.

کدهای خطای سرپرست SDK

جدول زیر کدهای خطای Firebase Admin FCM API و شرح آن‌ها را، ازجمله مراحل حل‌وفصل توصیه‌شده، فهرست می‌کند.

کد خطا	شرح و مراحل حل‌وفصل
messaging/invalid-argument	متغیر مستقل نامعتبری برای روش FCM ارائه شده است. پیام خطا باید حاوی اطلاعات بیشتری باشد.
messaging/invalid-recipient	گیرنده موردنظر پیام نامعتبر است. پیام خطا باید حاوی اطلاعات بیشتری باشد.
messaging/invalid-payload	شیء بار داده پیام نامعتبر ارائه شده است. پیام خطا باید حاوی اطلاعات بیشتری باشد.
messaging/invalid-data-payload-key	بار داده پیام حاوی کلید نامعتبر است. برای کلیدهای محدودشده، اسناد مرجع BaseMessage.data را ببینید.
messaging/payload-size-limit-exceeded	پایه‌بار پیام ارائه‌شده از حد مجاز FCM بیشتر است. حدمجاز برای اکثر پیام‌ها ۴۰۹۶ بایت است. برای پیام‌های ارسال‌شده به موضوعات، حد مجاز ۲۰۴۸ بایت است. اندازه کل بار مفید شامل کلیدها و مقادیر می‌شود.
messaging/invalid-options	شیء گزینه‌های پیام نامعتبر ارائه شده است. پیام خطا باید حاوی اطلاعات بیشتری باشد.
messaging/invalid-registration-token	کد ثبت نامعتبر ارائه شده است. مطمئن شوید که با کد ثبت دریافتی برنامه کارخواه از ثبت‌نام در FCM مطابقت داشته باشد. آن را کوتاه نکنید یا نویسه دیگری به آن اضافه نکنید.
messaging/registration-token-not-registered	کد ثبت ارائه‌شده ثبت نشده است. یک کد ثبت‌نام که قبلاً معتبر بوده است ممکن است به دلایل مختلفی لغو ثبت‌نام شود، ازجمله: برنامه مشتری ثبت‌نام خود را از FCM لغو کرد. ثبت برنامه مشتری به‌طور خودکار لغو شد. این اتفاق زمانی رخ می‌دهد که کاربر برنامه را حذف نصب کند یا در پلاتفرم‌های Apple، اگر «سرویس بازخورد APN» گزارش دهد که APN نامعتبر است. توکن ثبت منقضی شده است. برای مثال، Google ممکن است تصمیم بگیرد نشان‌های ثبت را بازآوری کند یا ممکن است نشان APN برای دستگاه‌های 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	اطلاعات اعتباری استفاده‌شده برای اصالت‌سنجی این کیت توسعه نرم‌افزار اجازه ندارد به دستگاه مربوط به کد ثبت ارائه‌شده پیام ارسال کند. مطمئن شوید که هم اعتبارنامه و هم کد ثبت به یک پروژه Firebase تعلق داشته باشند. برای دریافت اسناد مربوط به نحوه اصالت‌سنجی Firebase Admin SDK، افزودن Firebase به برنامه را ببینید.
messaging/authentication-error	کیت توسعه نرم‌افزار (SDK) نتوانست در سرورهای FCM اصالت‌سنجی کند. مطمئن شوید که Firebase Admin SDK را با اطلاعات اعتباری‌ای اصالت‌سنجی می‌کنید که اجازه‌های لازم برای ارسال پیام‌های FCM را داشته باشد. برای دریافت اسناد مربوط به نحوه اصالت‌سنجی Firebase Admin SDK، افزودن Firebase به برنامه را ببینید.
messaging/server-unavailable	سرور FCM نتوانست درخواست را به‌موقع پردازش کند. باید همان درخواست را دوباره امتحان کنید، اما باید: اگر سرصفحه Retry-After در پاسخ «سرور اتصال» FCM گنجانده شده است، آن را رعایت کنید. در سازوکار تکرار مجدد، از عقب‌نشینی نمایی استفاده کنید. برای مثال، اگر قبل‌از اولین تلاش مجدد یک ثانیه صبر کردید، قبل‌از تلاش بعدی حداقل دو ثانیه صبر کنید، سپس چهار ثانیه، و به افزایش فاصله زمانی ادامه دهید. اگر چند پیام ارسال می‌کنید، هرکدام را به‌طور مستقل با مقدار تصادفی دیگری به‌تأخیر بیندازید تا از صدور درخواست جدید برای همه پیام‌ها به‌طور هم‌زمان جلوگیری شود. فرستندگانی که مشکل ایجاد می‌کنند ممکن است در فهرست غیرمجازها قرار بگیرند.
messaging/internal-error	سرور FCM هنگام پردازش درخواست با خطایی مواجه شد. می‌توانید همان درخواست را با رعایت الزامات فهرست‌شده در ردیف messaging/server-unavailable قبلی دوباره امتحان کنید. اگر خطا برطرف نشد، لطفاً مشکل را به کانال پشتیبانی گزارش اشکال ما گزارش دهید.
messaging/unknown-error	خطای سرور ناشناخته‌ای برگردانده شد. برای جزئیات بیشتر، پاسخ خام سرور را در پیام خطا ببینید. اگر این خطا را دریافت کردید، لطفاً پیام خطای کامل را به کانال پشتیبانی گزارش اشکال ما گزارش کنید.