کدهای خطای FCM

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

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

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

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

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

{
  "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 تجاوز نکند: 4096 بایت برای بیشتر پیام‌ها، یا 2048 بایت در مورد پیام‌ها به موضوعات. این شامل کلیدها و مقادیر می شود. کلید داده نامعتبر : بررسی کنید که داده‌های محموله حاوی کلید (مانند از، یا gcm، یا هر مقداری که پیشوند Google است) نباشد که به صورت داخلی توسط FCM استفاده می‌شود. توجه داشته باشید که برخی از کلمات (مانند collapse_key) توسط FCM نیز استفاده می شوند اما در payload مجاز هستند، در این صورت مقدار payload با مقدار FCM لغو می شود. TTL نامعتبر : بررسی کنید که مقدار استفاده شده در ttl یک عدد صحیح باشد که مدت زمان بر حسب ثانیه را بین 0 تا 2,419,200 (4 هفته) نشان می دهد. پارامترهای نامعتبر : بررسی کنید که پارامترهای ارائه شده نام و نوع مناسبی داشته باشند.
UNREGISTERED (کد خطای HTTP = 404) نمونه برنامه از FCM ثبت نشده است. این معمولاً به این معنی است که توکن مورد استفاده دیگر معتبر نیست و باید از یک توکن جدید استفاده شود.	این خطا می تواند ناشی از گم شدن توکن های ثبت نام یا توکن های ثبت نشده باشد. عدم ثبت نام : اگر هدف پیام یک مقدار token است، بررسی کنید که درخواست حاوی نشانه ثبت باشد. ثبت نشده : یک رمز ثبت موجود ممکن است در تعدادی از سناریوها از بین برود، از جمله: - اگر برنامه مشتری با FCM لغو ثبت نام کند. - اگر برنامه مشتری به طور خودکار ثبت نشده باشد، در صورتی که کاربر برنامه را حذف نصب کند، ممکن است اتفاق بیفتد. به عنوان مثال، در iOS، اگر سرویس بازخورد APNs توکن APN را نامعتبر گزارش کند. - اگر رمز ثبت نام منقضی شود (برای مثال، ممکن است Google تصمیم بگیرد که نشانه های ثبت نام را به روز کند، یا نشانه APNs برای دستگاه های iOS منقضی شده است). - اگر برنامه سرویس گیرنده به روز شده است اما نسخه جدید برای دریافت پیام پیکربندی نشده است. برای همه این موارد، این رمز ثبت نام را از سرور برنامه حذف کنید و استفاده از آن برای ارسال پیام را متوقف کنید.
SENDER_ID_MISMATCH (کد خطای HTTP = 403) شناسه فرستنده احراز هویت شده با شناسه فرستنده رمز ثبت نام متفاوت است.	یک نشانه ثبت نام به گروه خاصی از فرستندگان گره خورده است. هنگامی که یک برنامه مشتری برای FCM ثبت نام می کند، باید مشخص کند که کدام فرستنده مجاز به ارسال پیام است. هنگام ارسال پیام به برنامه مشتری باید از یکی از آن شناسه های فرستنده استفاده کنید. اگر به فرستنده دیگری بروید، نشانه‌های ثبت‌نام موجود کار نمی‌کنند.
QUOTA_EXCEEDED (کد خطای HTTP = 429) از محدودیت ارسال برای هدف پیام فراتر رفت. پسوندی از نوع google.rpc.QuotaFailure برگردانده می شود تا مشخص شود از کدام سهمیه فراتر رفته است.	این خطا می تواند ناشی از فراتر رفتن از سهمیه نرخ پیام، فراتر از سهمیه نرخ پیام دستگاه، یا فراتر از سهمیه نرخ پیام موضوعی باشد. نرخ پیام بیش از حد : نرخ ارسال پیام ها بسیار بالا است. شما باید نرخ کلی ارسال پیام را کاهش دهید. از عقب نشینی نمایی با حداقل تاخیر اولیه 1 دقیقه برای امتحان مجدد پیام های رد شده استفاده کنید. نرخ پیام دستگاه بیش از حد است : نرخ پیام‌ها به یک دستگاه خاص بسیار زیاد است. محدودیت نرخ پیام برای یک دستگاه را ببینید . تعداد پیام‌های ارسال شده به این دستگاه را کاهش دهید و برای ارسال مجدد از عقب‌نشینی نمایی استفاده کنید. نرخ پیام موضوع بیش از حد است : نرخ پیام به مشترکین یک موضوع خاص بسیار زیاد است. تعداد پیام‌های ارسال‌شده برای این موضوع را کاهش دهید و برای ارسال مجدد از عقب‌نشینی نمایی با حداقل تأخیر اولیه ۱ دقیقه استفاده کنید.
UNAVAILABLE (کد خطای HTTP = 503) سرور بیش از حد بارگیری شده است.	سرور نتوانست به موقع درخواست را پردازش کند. همان درخواست را دوباره امتحان کنید، اما باید: - اگر هدر Retry-After در پاسخ سرور اتصال FCM گنجانده شده است، به آن احترام بگذارید. - اجرای عقب نشینی نمایی در مکانیسم تلاش مجدد. (مثلاً اگر یک ثانیه قبل از اولین تلاش مجدد صبر کرده اید، حداقل دو ثانیه قبل از امتحان بعدی صبر کنید، سپس 4 ثانیه و غیره). اگر چندین پیام ارسال می‌کنید، از جیترینگ استفاده کنید. برای اطلاعات بیشتر، به مدیریت مجدد مراجعه کنید ، یا داشبورد وضعیت FCM را بررسی کنید تا تشخیص دهید که آیا اختلالات مداوم سرویس بر FCM تأثیر می گذارد یا خیر. فرستنده هایی که مشکل ایجاد می کنند در معرض خطر رد شدن هستند.
INTERNAL (کد خطای HTTP = 500) یک خطای داخلی ناشناخته رخ داد.	سرور هنگام تلاش برای پردازش درخواست با خطایی مواجه شد. می‌توانید همان درخواست را به دنبال پیشنهادهایی که در «کنترل تلاش‌های مجدد» یا بررسی داشبورد وضعیت FCM ارائه شده است، دوباره امتحان کنید. برای شناسایی اینکه آیا اختلالات مداوم سرویس بر FCM تأثیر می گذارد یا خیر. اگر خطا ادامه داشت، لطفاً با پشتیبانی Firebase تماس بگیرید.
THIRD_PARTY_AUTH_ERROR (کد خطای HTTP = 401) گواهینامه APN یا کلید تأیید وب فشار نامعتبر یا گم شده بود.	پیامی که برای یک دستگاه iOS یا ثبت وب پوش هدف گذاری شده است ارسال نشد. اعتبار اعتبارنامه توسعه و تولید خود را بررسی کنید.

کدهای خطای Admin 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 توکن APN را نامعتبر گزارش کرده باشد، ممکن است این اتفاق بیفتد. ژتون ثبت نام منقضی شده است. برای مثال، ممکن است Google تصمیم بگیرد که نشانه‌های ثبت نام را به‌روزرسانی کند یا نشانه‌های 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	پیامی که برای دستگاه Apple مورد هدف قرار گرفته است ارسال نشد زیرا گواهینامه SSL APN های مورد نیاز آپلود نشده یا منقضی شده است. اعتبار گواهی های توسعه و تولید خود را بررسی کنید.
messaging/mismatched-credential	اعتبار مورد استفاده برای احراز هویت این SDK مجوز ارسال پیام به دستگاه مربوط به رمز ثبت نام ارائه شده را ندارد. اطمینان حاصل کنید که اعتبار و رمز ثبت نام هر دو متعلق به یک پروژه Firebase هستند. برای مستندات مربوط به نحوه احراز هویت Firebase Admin SDK s ، به افزودن Firebase به برنامه خود مراجعه کنید.
messaging/authentication-error	SDK نتوانست در سرورهای FCM احراز هویت شود. اطمینان حاصل کنید که Firebase Admin SDK با اعتباری که دارای مجوزهای مناسب برای ارسال پیام‌های FCM است، احراز هویت کنید. برای مستندات مربوط به نحوه احراز هویت Firebase Admin SDK s ، به افزودن Firebase به برنامه خود مراجعه کنید.
messaging/server-unavailable	سرور FCM نتوانست به موقع درخواست را پردازش کند. شما باید همان درخواست را دوباره امتحان کنید، اما باید: اگر سرصفحه Retry-After در پاسخ سرور اتصال FCM گنجانده شده است، به آن احترام بگذارید. در مکانیسم تلاش مجدد خود، عقب نشینی نمایی را اجرا کنید. به عنوان مثال، اگر قبل از اولین تلاش مجدد یک ثانیه صبر کرده اید، حداقل دو ثانیه قبل از امتحان بعدی و سپس چهار ثانیه صبر کنید و به افزایش فاصله ثانیه ها ادامه دهید. اگر چندین پیام ارسال می کنید، هر کدام را به طور مستقل با مقدار تصادفی اضافی به تاخیر بیندازید تا از صدور درخواست جدید برای همه پیام ها به طور همزمان جلوگیری کنید. فرستنده هایی که مشکل ایجاد می کنند، در معرض خطر قرار گرفتن در لیست مسدود هستند.
messaging/internal-error	سرور FCM هنگام تلاش برای پردازش درخواست با خطا مواجه شد. می توانید با پیروی از الزامات فهرست شده در ردیف قبلی messaging/server-unavailable همان درخواست را دوباره امتحان کنید. اگر خطا ادامه داشت، لطفاً مشکل را به کانال پشتیبانی گزارش اشکال ما گزارش دهید.
messaging/unknown-error	یک خطای ناشناخته سرور برگردانده شد. برای جزئیات بیشتر پاسخ سرور خام را در پیام خطا مشاهده کنید. اگر این خطا را دریافت کردید، لطفاً پیام خطای کامل را به کانال پشتیبانی گزارش اشکال گزارش دهید.