کدهای خطای 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 = 400) پارامترهای درخواست نامعتبر بودند. افزونه‌ای از نوع google.rpc.BadRequest برگردانده می‌شود تا مشخص کند کدام فیلد نامعتبر بوده است.	دلایل احتمالی شامل ثبت نام نامعتبر، نام بسته نامعتبر، پیام خیلی بزرگ، کلید داده نامعتبر، TTL نامعتبر، یا دیگر پارامترهای نامعتبر است. ثبت نام نامعتبر: قالب کد ثبت نامی که به سرور ارسال می‌کنید را بررسی کنید. مطمئن شوید که با کد ثبت دریافتی برنامه کارخواه از ثبت در FCM مطابقت داشته باشد. نشان را کوتاه نکنید یا نویسه‌های اضافی اضافه نکنید. نام بسته نامعتبر است: مطمئن شوید پیام به نشانی یک کد ثبت ارسال شده است که نام بسته‌اش با مقدار ارسال‌شده در درخواست مطابقت دارد. پیام خیلی بزرگ است: بررسی کنید که اندازه کل داده‌های پایه‌بار موجود در پیام از محدودیت‌های FCM فراتر نرود: ۴۰۹۶ بایت برای اکثر پیام‌ها، یا ۲۰۴۸ بایت در پیام‌های مربوط به موضوعات. این شامل هم کلیدها و هم مقادیر می‌شود. کلید داده نامعتبر: بررسی کنید که داده‌های پیام‌واره حاوی کلیدی (مثل from،‏ gcm، یا هر مقدار پیشوندی با google) که FCM به‌صورت داخلی استفاده می‌کند نباشد. توجه داشته باشید که برخی‌از کلمات (مثل collapse_key) توسط FCM نیز استفاده می‌شوند اما در بار مفید مجاز هستند، در این صورت مقدار بار مفید با مقدار FCM ملغی می‌شود. زمان بقای نامعتبر: بررسی کنید که مقدار استفاده‌شده در زمان بقا یک عدد صحیح باشد که نشان‌دهنده مدت زمان برحسب ثانیه بین ۰ و ۲٬۴۱۹٬۲۰۰ (۴ هفته) است. پارامترهای نامعتبر: بررسی کنید که پارامترهای ارائه‌شده نام و نوع صحیح را داشته باشند.
UNREGISTERED (کد خطای HTTP = 404) نمونه برنامه از FCM لغو ثبت شد. این معمولاً به این معنی است که نمودارافزار استفاده‌شده دیگر معتبر نیست و باید از نمودارافزار جدیدی استفاده شود.	این خطا می‌تواند به‌دلیل نبودن نشان‌های ثبت یا نشان‌های ثبت‌نشده باشد. ثبت‌نام وجود ندارد: اگر هدف پیام مقدار token باشد، بررسی کنید که درخواست حاوی کد ثبت‌نام باشد. ثبت‌نشده: در چند سناریو ممکن است یک کد ثبت موجود دیگر معتبر نباشد، ازجمله: - اگر برنامه کارخواه از FCM لغو ثبت کند. - اگر برنامه مشتری به‌طور خودکار ثبت‌نامش لغو شود، که می‌تواند درصورتی‌که کاربر برنامه را حذف نصب کند اتفاق بیفتد. برای مثال، در iOS، اگر «سرویس بازخورد APNs» نشان APNs را به‌عنوان نامعتبر گزارش کند. - اگر کد ثبت منقضی شود (برای مثال، Google ممکن است تصمیم بگیرد کد ثبت را بازآوری کند، یا کد APNs برای دستگاه‌های iOS منقضی شده باشد). - اگر برنامه مشتری به‌روز شده باشد اما نسخه جدید برای دریافت پیام پیکربندی نشده باشد. برای همه این موارد، این کد ثبت را از سرور برنامه بردارید و از آن برای ارسال پیام استفاده نکنید.
SENDER_ID_MISMATCH (کد خطای HTTP = 403) شناسه فرستنده اصیل با شناسه فرستنده برای کد ثبت متفاوت است.	رمز ثبت به گروه خاصی از فرستندگان مرتبط است. وقتی برنامه مشتری برای FCM ثبت می‌شود، باید مشخص کند کدام فرستندگان اجازه دارند پیام ارسال کنند. هنگام ارسال پیام به برنامه مشتری، باید از یکی از آن شناسه‌های فرستنده استفاده کنید. اگر به فرستنده دیگری تغییر دهید، نشان‌های ثبت موجود کار نخواهند کرد.
QUOTA_EXCEEDED (کد خطای HTTP = 429) از حد ارسال برای هدف پیام فراتر رفته است. افزونه‌ای از نوع google.rpc.QuotaFailure برگردانده می‌شود تا مشخص کند از کدام سهمیه فراتر رفته‌اید.	این خطا می‌تواند ناشی از فراتر رفتن از سهمیه نرخ پیام، فراتر رفتن از سهمیه نرخ پیام دستگاه، یا فراتر رفتن از سهمیه نرخ پیام موضوع باشد. نرخ پیام از حد مجاز فراتر رفته است: نرخ ارسال پیام بسیار بالا است. باید نرخ کلی ارسال پیام را کاهش دهید. برای تلاش مجدد برای پیام‌های ردشده، از پس‌رفت نمایی با حداقل تأخیر اولیه ۱ دقیقه استفاده کنید. نرخ پیام دستگاه از حد مجاز فراتر رفته است: نرخ پیام‌های ارسالی به دستگاهی خاص بسیار بالا است. محدودیت نرخ پیام به یک دستگاهرا ببینید. تعداد پیام‌های ارسالی به این دستگاه را کاهش دهید و از «پس‌رفت نمایی» برای تلاش مجدد برای ارسال استفاده کنید. نرخ پیام موضوع از حد مجاز فراتر رفته است: نرخ پیام‌های ارسالی به مشترکین یک موضوع خاص بسیار بالا است. تعداد پیام‌های ارسالی برای این موضوع را کاهش دهید و از پس‌گیری نمایی با حداقل تأخیر اولیه ۱ دقیقه برای تلاش مجدد برای ارسال استفاده کنید.
‫UNAVAILABLE (کد خطای HTTP = 503) سرور اضافه‌بار دارد.	سرور نتوانست درخواست را به‌موقع پردازش کند. همان درخواست را دوباره امتحان کنید، اما باید: - اگر سرایند «تلاش مجدد پس‌از» در پاسخ «سرور اتصال FCM» گنجانده شده است، آن را رعایت کنید. - عقب‌گرد نمایی را در سازوکار تلاش مجدد پیاده‌سازی کنید. (برای مثال، اگر یک ثانیه قبل‌از اولین تلاش مجدد صبر کردید، حداقل دو ثانیه قبل‌از تلاش مجدد بعدی صبر کنید، سپس ۴ ثانیه و به همین ترتیب). اگر چندین پیام ارسال می‌کنید، لرزش را درنظر بگیرید. برای اطلاعات بیشتر، مدیریت تلاش‌های مجددرا ببینید، یا داشبورد وضعیت FCM را بررسی کنید تا مشخص کنید آیا تداخلی در سرویس درحال انجام وجود دارد که بر FCM تأثیر بگذارد. فرستندگانی که باعث ایجاد مشکل می‌شوند درمعرض خطر قرار گرفتن در فهرست غیرمجاز قرار دارند.
‫INTERNAL (کد خطای HTTP = 500) خطای داخلی ناشناخته‌ای رخ داد.	سرور هنگام پردازش درخواست با خطا مواجه شد. می‌توانید درخواست یکسانی را با دنبال کردن پیشنهادهای مدیریت تلاش‌های مجدد یا بررسی داشبورد وضعیت FCM دوباره امتحان کنید. برای شناسایی اینکه آیا اختلالات سرویس جاری وجود دارد که بر FCM تأثیر بگذارد. اگر خطا ادامه داشت، لطفاً با پشتیبانی Firebase تماس بگیرید.
THIRD_PARTY_AUTH_ERROR گواهینامه APNs یا کلید اصالت‌سنجی پیام‌رسانی تحت وب نامعتبر یا موجود نیست (کد خطای HTTP = 401).	پیامی که دستگاه iOS یا ثبت فشار وب را هدف‌یابی کرده است ارسال نشد. اعتبار اطلاعات اعتباری توسعه و تولید خود را بررسی کنید.

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

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

کد خطا	شرح و مراحل حل‌وفصل
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، اگر «سرویس بازخورد APNs» نشان APNs را نامعتبر گزارش کند. رمز ثبت‌نام منقضی شده است. برای مثال، ممکن است 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	اطلاعات اعتباری استفاده‌شده برای اصالت‌سنجی این کیت توسعه نرم‌افزار اجازه ندارد به دستگاه مربوط به کد ثبت ارائه‌شده پیام ارسال کند. مطمئن شوید هم اطلاعات اعتباری و هم کد ثبت متعلق به یک پروژه 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	خطای ناشناخته‌ای از سرور برگردانده شد. برای جزئیات بیشتر، پاسخ سرور خام را در پیام خطا ببینید. اگر این خطا را دریافت کردید، لطفاً پیام خطای کامل را به کانال پشتیبانی گزارش اشکال ما گزارش کنید.