کدهای خطای 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 = 429) از حد ارسال برای هدف پیام فراتر رفته است. افزونه‌ای از نوع google.rpc.QuotaFailure برگردانده می‌شود تا مشخص کند از کدام سهمیه فراتر رفته‌اید.	این خطا می‌تواند ناشی از فراتر رفتن از سهمیه نرخ پیام، فراتر رفتن از سهمیه نرخ پیام دستگاه، یا فراتر رفتن از سهمیه نرخ پیام موضوع باشد. از نرخ پیام فراتر رفته است: نرخ ارسال پیام‌ها بسیار بالا است. باید نرخ کلی ارسال پیام را کاهش دهید. برای تلاش مجدد برای پیام‌های ردشده، از پس‌رفت نمایی با حداقل تأخیر اولیه ۱ دقیقه استفاده کنید. نرخ پیام دستگاه فراتر رفته است: نرخ پیام‌ها به دستگاهی خاص بسیار بالا است. محدودیت نرخ پیام به یک دستگاهرا ببینید. تعداد پیام‌های ارسالی به این دستگاه را کاهش دهید و از «پس‌رفت نمایی» برای تلاش مجدد برای ارسال استفاده کنید. نرخ پیام موضوع از حد مجاز فراتر رفته است: نرخ پیام‌های ارسالی به مشترکین یک موضوع خاص بسیار بالا است. تعداد پیام‌های ارسالی برای این موضوع را کاهش دهید و از پس‌گیری نمایی با حداقل تأخیر اولیه ۱ دقیقه برای تلاش مجدد برای ارسال استفاده کنید.
UNAVAILABLE (کد خطای HTTP = ‏۵۰۳) سرور اضافه‌بار دارد.	سرور نتوانست درخواست را به‌موقع پردازش کند. همان درخواست را دوباره امتحان کنید، اما باید: - اگر سرصفحه Retry-After در پاسخ FCM Connection Server گنجانده شده است، آن را رعایت کنید. - عقب‌گرد نمایی را در سازوکار تکرار مجدد خود پیاده‌سازی کنید. (مثلاً اگر قبل‌از اولین تلاش مجدد یک ثانیه صبر کردید، قبل‌از تلاش مجدد بعدی حداقل دو ثانیه صبر کنید، سپس ۴ ثانیه و به همین ترتیب). اگر چندین پیام ارسال می‌کنید، لرزش را درنظر بگیرید. برای اطلاعات بیشتر، مدیریت تلاش‌های مجددرا ببینید، یا داشبورد وضعیت FCM را بررسی کنید تا ببینید آیا اختلالات سرویس درحال‌انجام وجود دارد که بر FCM تأثیر بگذارد. فرستندگانی که باعث ایجاد مشکل می‌شوند درمعرض خطر قرار گرفتن در فهرست غیرمجاز قرار دارند.
‫INTERNAL (کد خطای HTTP = 500) خطای داخلی ناشناخته‌ای رخ داد.	سرور هنگام پردازش درخواست با خطایی مواجه شد. می‌توانید همان درخواست را با دنبال کردن پیشنهادهای موجود در رسیدگی به تلاش‌های مجدد یا بررسی داشبورد وضعیت FCM دوباره امتحان کنید. برای شناسایی اینکه آیا اختلالات سرویس جاری وجود دارد که بر FCM تأثیر بگذارد. اگر خطا ادامه داشت، لطفاً با پشتیبانی Firebase تماس بگیرید.
THIRD_PARTY_AUTH_ERROR (کد خطای HTTP‏ = ۴۰۱) گواهی APNs یا کلید اصالت‌سنجی وب push نامعتبر یا مفقود بود.	پیامی که برای دستگاه 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 بیشتر است. حدمجاز برای اکثر پیام‌ها ۴۰۹۶ بایت است. برای پیام‌های ارسال‌شده به موضوعات، حد مجاز ۲۰۴۸ بایت است. اندازه کل بار شامل هر دو کلید و مقدار است.
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 را هدف‌یابی کرده است ارسال نشد زیرا گواهینامه SSL موردنیاز APNs بارگذاری نشده است یا منقضی شده است. اعتبار گواهی‌های توسعه و تولیدتان را بررسی کنید.
messaging/mismatched-credential	اطلاعات اعتباری استفاده‌شده برای اصالت‌سنجی این کیت توسعه نرم‌افزار اجازه ندارد به دستگاه مربوط به کد ثبت ارائه‌شده پیام ارسال کند. مطمئن شوید هم اطلاعات اعتباری و هم کد ثبت متعلق به یک پروژه Firebase باشند. برای دریافت اسناد مربوط به نحوه اصالت‌سنجی Firebase Admin SDK، افزودن Firebase به برنامه را ببینید.
messaging/authentication-error	«کیت توسعه نرم‌افزار» نتوانست در سرورهای 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	خطای سرور ناشناخته‌ای برگردانده شد. برای جزئیات بیشتر، پاسخ سرور خام را در پیام خطا ببینید. اگر این خطا را دریافت کردید، لطفاً پیام خطای کامل را به کانال پشتیبانی گزارش اشکال ما گزارش کنید.