کدهای خطای 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"
      }
    ]
   }
}

توجه داشته باشید که هر دو پیام کد و وضعیت یکسانی دارند، اما آرایه details شامل مقادیری با انواع مختلف است. مثال اول دارای نوع type.googleapis.com/google.rpc.BadRequest است که نشان دهنده خطا در مقادیر درخواست است. مثال دوم با نوع type.googleapis.com/google.firebase.fcm.v1.FcmError دارای یک خطای خاص FCM است. برای بسیاری از خطاها، آرایه details شامل اطلاعاتی است که برای اشکال زدایی و یافتن راه حل نیاز دارید.

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

کد خطا	مراحل شرح و حل مسئله
UNSPECIFIED_ERROR اطلاعات بیشتری در مورد این خطا در دسترس نیست.	هیچ کدام.
INVALID_ARGUMENT (کد خطای HTTP = ۴۰۰) پارامترهای درخواست نامعتبر بودند. پسوندی از نوع google.rpc.BadRequest برگردانده می‌شود تا مشخص کند کدام فیلد نامعتبر بوده است.	دلایل احتمالی شامل ثبت نام نامعتبر، نام بسته نامعتبر، پیام خیلی بزرگ، کلید داده نامعتبر، TTL نامعتبر یا سایر پارامترهای نامعتبر است. ثبت نام نامعتبر : قالب توکن ثبت نامی که به سرور ارسال می‌کنید را بررسی کنید. مطمئن شوید که با توکن ثبت نامی که برنامه کلاینت از ثبت نام با FCM دریافت می‌کند، مطابقت دارد. توکن را کوتاه نکنید یا کاراکترهای اضافی اضافه نکنید. نام بسته نامعتبر : مطمئن شوید که پیام به توکن ثبتی ارسال شده است که نام بسته آن با مقدار ارسالی در درخواست مطابقت دارد. پیام خیلی بزرگ است : بررسی کنید که اندازه کل داده‌های بار داده موجود در یک پیام از محدودیت‌های FCM تجاوز نکند: ۴۰۹۶ بایت برای اکثر پیام‌ها، یا ۲۰۴۸ بایت در مورد پیام‌های مربوط به تاپیک‌ها. این شامل کلیدها و مقادیر می‌شود. کلید داده نامعتبر : بررسی کنید که داده‌های payload حاوی کلیدی (مانند from، یا gcm، یا هر مقداری که با پیشوند google مشخص شده است) که به صورت داخلی توسط FCM استفاده می‌شود، نباشند. توجه داشته باشید که برخی از کلمات (مانند collapse_key) توسط FCM نیز استفاده می‌شوند اما در payload مجاز هستند، که در این صورت مقدار payload توسط مقدار FCM لغو می‌شود. TTL نامعتبر : بررسی کنید که مقدار استفاده شده در ttl یک عدد صحیح باشد که نشان دهنده مدت زمان بر حسب ثانیه بین 0 تا 2,419,200 (4 هفته) باشد. پارامترهای نامعتبر : بررسی کنید که پارامترهای ارائه شده نام و نوع صحیحی داشته باشند.
UNREGISTERED (کد خطای HTTP = 404) نمونه برنامه از FCM ثبت نشده است. این معمولاً به این معنی است که توکن استفاده شده دیگر معتبر نیست و باید از یک توکن جدید استفاده شود.	این خطا می‌تواند ناشی از فقدان توکن‌های ثبت نام یا توکن‌های ثبت نشده باشد. فقدان ثبت نام : اگر هدف پیام یک مقدار token است، بررسی کنید که درخواست حاوی یک توکن ثبت نام باشد. ثبت نشده : یک توکن ثبت موجود ممکن است در چندین سناریو از جمله موارد زیر اعتبار خود را از دست بدهد: - اگر برنامه کلاینت از FCM لغو ثبت شود. - اگر برنامه کلاینت به طور خودکار لغو ثبت شود، که این اتفاق می‌تواند در صورت حذف نصب برنامه توسط کاربر رخ دهد. برای مثال، در iOS، اگر سرویس بازخورد APNها، توکن APNها را نامعتبر گزارش کند. - اگر توکن ثبت نام منقضی شود (برای مثال، گوگل ممکن است تصمیم بگیرد توکن‌های ثبت نام را به‌روزرسانی کند، یا توکن APN برای دستگاه‌های iOS منقضی شده باشد). - اگر برنامه کلاینت به‌روزرسانی شده باشد اما نسخه جدید برای دریافت پیام‌ها پیکربندی نشده باشد. برای همه این موارد، این توکن ثبت نام را از سرور برنامه حذف کنید و استفاده از آن را برای ارسال پیام متوقف کنید.
SENDER_ID_MISMATCH (کد خطای HTTP = 403) شناسه فرستنده احراز هویت شده با شناسه فرستنده برای توکن ثبت متفاوت است.	یک توکن ثبت به گروه خاصی از فرستنده‌ها گره خورده است. وقتی یک برنامه‌ی کلاینت برای FCM ثبت نام می‌کند، باید مشخص کند که کدام فرستنده‌ها مجاز به ارسال پیام هستند. شما باید هنگام ارسال پیام به برنامه‌ی کلاینت از یکی از آن شناسه‌های فرستنده استفاده کنید. اگر به فرستنده‌ی دیگری تغییر دهید، توکن‌های ثبت موجود کار نخواهند کرد.
QUOTA_EXCEEDED (کد خطای HTTP = ۴۲۹) محدودیت ارسال برای پیام هدف بیش از حد مجاز است. پسوندی از نوع google.rpc.QuotaFailure برگردانده می‌شود تا مشخص کند کدام سهمیه بیش از حد مجاز بوده است.	این خطا می‌تواند ناشی از سهمیه‌ی بیش از حد مجاز نرخ پیام، سهمیه‌ی بیش از حد مجاز نرخ پیام دستگاه یا سهمیه‌ی بیش از حد مجاز نرخ پیام موضوع باشد. نرخ ارسال پیام از حد مجاز فراتر رفته است : نرخ ارسال پیام‌ها بسیار بالاست. شما باید نرخ کلی ارسال پیام‌ها را کاهش دهید. برای امتحان مجدد پیام‌های رد شده، از روش بازگشت نمایی با حداقل تأخیر اولیه ۱ دقیقه استفاده کنید. نرخ پیام دستگاه از حد مجاز فراتر رفته است : نرخ پیام‌ها به یک دستگاه خاص بسیار بالا است. به محدودیت نرخ پیام برای یک دستگاه واحد مراجعه کنید . تعداد پیام‌های ارسالی به این دستگاه را کاهش دهید و برای تلاش مجدد ارسال از روش کاهش نمایی استفاده کنید. نرخ پیام‌های موضوعی از حد مجاز فراتر رفت : نرخ پیام‌ها به مشترکین یک موضوع خاص بسیار بالاست. تعداد پیام‌های ارسالی برای این موضوع را کاهش دهید و از روش بازگشت نمایی با حداقل تأخیر اولیه ۱ دقیقه برای تلاش مجدد ارسال استفاده کنید.
UNAVAILABLE (کد خطای HTTP = 503) سرور بیش از حد بارگذاری شده است.	سرور نتوانست درخواست را به موقع پردازش کند. همان درخواست را دوباره امتحان کنید، اما باید: - اگر هدر Retry-After در پاسخ سرور اتصال FCM وجود دارد، آن را رعایت کنید. - در مکانیزم تلاش مجدد خود، بازگشت نمایی (exponential backoff) را پیاده‌سازی کنید. (مثلاً اگر قبل از اولین تلاش مجدد، یک ثانیه صبر کرده‌اید، حداقل دو ثانیه قبل از تلاش بعدی صبر کنید، سپس ۴ ثانیه و به همین ترتیب). اگر چندین پیام ارسال می‌کنید، اعمال لرزش (jittering) را در نظر بگیرید. برای اطلاعات بیشتر، به مدیریت تلاش‌های مجدد مراجعه کنید ، یا داشبورد وضعیت FCM را بررسی کنید تا مشخص شود که آیا اختلالات سرویس مداومی وجود دارد که FCM را تحت تأثیر قرار می‌دهد یا خیر. فرستندگانی که مشکل ایجاد می‌کنند، در معرض خطر رد شدن در لیست هستند.
INTERNAL (کد خطای HTTP = 500) یک خطای داخلی ناشناخته رخ داده است.	سرور هنگام تلاش برای پردازش درخواست با خطایی مواجه شد. می‌توانید با دنبال کردن پیشنهادات موجود در بخش «مدیریت تلاش‌های مجدد» یا بررسی داشبورد وضعیت FCM ، همان درخواست را دوباره امتحان کنید تا مشخص شود که آیا اختلالات سرویس مداومی وجود دارد که FCM را تحت تأثیر قرار می‌دهد یا خیر. اگر خطا همچنان ادامه داشت، لطفاً با پشتیبانی Firebase تماس بگیرید.
THIRD_PARTY_AUTH_ERROR (کد خطای HTTP = ۴۰۱) گواهی APN یا کلید تأیید ارسال وب نامعتبر یا مفقود است.	پیامی که به دستگاه iOS یا ثبت نام در وب پوش ارسال شده باشد، قابل ارسال نیست. اعتبارنامه‌های توسعه و تولید خود را بررسی کنید.

کدهای خطای SDK مدیریت

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

کد خطا	مراحل شرح و حل مسئله
messaging/invalid-argument	یک آرگومان نامعتبر به روش FCM ارائه شده است. پیام خطا باید حاوی اطلاعات اضافی باشد.
messaging/invalid-recipient	گیرنده پیام مورد نظر نامعتبر است. پیام خطا باید حاوی اطلاعات اضافی باشد.
messaging/invalid-payload	یک شیء 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 لغو ثبت کرد. برنامه کلاینت به طور خودکار لغو ثبت شد. این اتفاق می‌تواند در صورتی رخ دهد که کاربر برنامه را حذف نصب کند یا در پلتفرم‌های اپل، اگر سرویس بازخورد APNها، توکن APNها را نامعتبر گزارش کند. توکن ثبت نام منقضی شده است. برای مثال، ممکن است گوگل تصمیم به به‌روزرسانی توکن‌های ثبت نام بگیرد یا ممکن است توکن APN برای دستگاه‌های اپل منقضی شده باشد. برنامه کلاینت به‌روزرسانی شد، اما نسخه جدید برای دریافت پیام‌ها پیکربندی نشده است. برای همه این موارد، این توکن ثبت نام را حذف کنید و استفاده از آن را برای ارسال پیام متوقف کنید.
messaging/invalid-package-name	این پیام به یک توکن ثبت نام ارسال شده است که نام بسته آن با گزینه restrictedPackageName ارائه شده مطابقت ندارد.
messaging/message-rate-exceeded	سرعت ارسال پیام به یک مخاطب خاص بسیار بالاست. تعداد پیام‌های ارسالی به این دستگاه یا موضوع را کاهش دهید و بلافاصله ارسال به این مخاطب را دوباره امتحان نکنید.
messaging/device-message-rate-exceeded	سرعت ارسال پیام به یک دستگاه خاص خیلی زیاد است. تعداد پیام‌های ارسالی به این دستگاه را کاهش دهید و بلافاصله ارسال به این دستگاه را دوباره امتحان نکنید.
messaging/topics-message-rate-exceeded	نرخ پیام‌ها به مشترکین یک موضوع خاص بسیار بالاست. تعداد پیام‌های ارسالی برای آن موضوع را کاهش دهید و بلافاصله ارسال به آن موضوع را دوباره امتحان نکنید.
messaging/too-many-topics	یک توکن ثبت نام در حداکثر تعداد تاپیک‌ها مشترک شده است و دیگر نمی‌توان در هیچ تاپیک دیگری مشترک شد.
messaging/invalid-apns-credentials	پیامی که به یک دستگاه اپل اختصاص داده شده بود، به دلیل آپلود نشدن یا منقضی شدن گواهی SSL مربوط به APN های مورد نیاز، قابل ارسال نبود. اعتبار گواهی‌های توسعه و تولید خود را بررسی کنید.
messaging/mismatched-credential	اعتبارنامه‌ای که برای احراز هویت این SDK استفاده می‌شود، مجوز ارسال پیام به دستگاه مربوط به توکن ثبت نام ارائه شده را ندارد. مطمئن شوید که اعتبارنامه و توکن ثبت نام هر دو متعلق به یک پروژه 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 وجود دارد، آن را رعایت کنید. در مکانیزم تلاش مجدد خود، یک روش بازگشت نمایی (exponential back-off) پیاده‌سازی کنید. برای مثال، اگر قبل از اولین تلاش مجدد، یک ثانیه صبر کرده‌اید، حداقل دو ثانیه قبل از تلاش مجدد بعدی، سپس چهار ثانیه صبر کنید و همچنان فاصله ثانیه‌ها را افزایش دهید. اگر چندین پیام ارسال می‌کنید، هر کدام را به طور مستقل با یک مقدار تصادفی اضافی به تأخیر بیندازید تا از صدور درخواست جدید برای همه پیام‌ها به طور همزمان جلوگیری شود. فرستندگانی که مشکل ایجاد می‌کنند، در معرض خطر بلاک شدن قرار می‌گیرند.
messaging/internal-error	سرور FCM هنگام تلاش برای پردازش درخواست با خطایی مواجه شد. می‌توانید همان درخواست را با رعایت الزامات ذکر شده در ردیف messaging/server-unavailable قبلی دوباره امتحان کنید. اگر خطا همچنان ادامه داشت، لطفاً مشکل را به کانال پشتیبانی گزارش اشکال ما گزارش دهید.
messaging/unknown-error	خطای ناشناخته‌ای از سمت سرور گزارش شد. برای جزئیات بیشتر، به پاسخ خام سرور در پیام خطا مراجعه کنید. در صورت دریافت این خطا، لطفاً متن کامل پیام خطا را به کانال پشتیبانی گزارش اشکال ما گزارش دهید.