کدهای خطای API ارسال پوش؛ معنی هر خطا و حذف توکن نامعتبر

ساختار پاسخ خطا

همه خطاهای وب‌سرویس‌های ارسال و سایر مسیرهای <code>/api/webservices</code> قالب یکسانی دارند. وضعیت HTTP دسته خطا را نشان می‌دهد و فیلد <code>error_code</code> علت دقیق را. در کد خود فقط بر اساس HTTP status و <code>error_code</code> تصمیم بگیرید؛ متن <code>message</code> برای نمایش به انسان است و ممکن است تغییر کند. در خطاهای مربوط به مخاطب، شناسه مشکل‌دار در <code>data</code> برمی‌گردد.

{
  "message": "هیچ مشترکی با این شناسه مستعار (alias) در این سرویس وجود ندارد.",
  "status_code": -1,
  "error_code": "ALIAS_NOT_FOUND",
  "data": { "alias": "customer-42" },
  "errors": true
}

خطاهای درخواست، دسترسی و حساب

خطاهای مخاطب: Subscriber ID، توکن، Alias و تاپیک

این خطاها یعنی درخواست سالم است اما مقصد قابل ارسال نیست. در ارسال تکی، شناسه مشکل‌دار و نوع آن (<code>subscriber_id</code> یا <code>fcm_token</code>) در <code>data</code> برمی‌گردد.

چه زمانی توکن یا شناسه را حذف کنم؟

خلاصه تصمیم برای کدهایی که به خود مخاطب مربوط‌اند. کدهای خطای درخواست، دسترسی و موجودی هیچ‌وقت دلیل حذف مخاطب نیستند.

ارسال به چند گیرنده: موفقیت جزئی و rejected_recipients

در send-group-message و send-group-lite-message با <code>subscriber_ids</code> یا <code>fcm_tokens</code>، و در send-via-subscriber-id، هر شناسه جداگانه بررسی می‌شود. پیام برای شناسه‌های معتبر در صف ارسال قرار می‌گیرد، پاسخ HTTP 200 است و شناسه‌های ردشده همراه با <code>error_code</code> هر کدام در <code>data.rejected_recipients</code> برمی‌گردند. فیلد <code>data.recipients</code> نشان می‌دهد برای هر شناسه کدام <code>notification_id</code> ساخته شده است. اگر هیچ شناسه‌ای قابل ارسال نباشد درخواست رد می‌شود: وقتی همه شناسه‌ها به یک علت رد شده باشند همان کد و HTTP status برمی‌گردد (مثلاً 404 با <code>SUBSCRIBER_NOT_FOUND</code>) و در غیر این صورت <code>NO_VALID_RECIPIENTS</code>. در send-via-alias هم مقدارهایی از <code>values</code> که مشترکی ندارند یا مشترک فعال ندارند با نوع <code>alias_value</code> در <code>rejected_recipients</code> گزارش می‌شوند. اگر شرط اختیاری <code>last_visit</code> را بفرستید، این شرط هم برای هر شناسه یا مقدار جداگانه بررسی می‌شود و موارد فاقد شرط با کد <code>LAST_VISIT_CONDITION_NOT_MET</code> در <code>rejected_recipients</code> می‌آیند. ارسال به تاپیک گزارش جداگانه برای هر مشترک ندارد.

{
  "message": "notification queued for send successfully",
  "status_code": 1,
  "data": {
    "notification_ids": ["9b2e0c0e-5c1f-4a39-9d55-0d6c1e2f7a10"],
    "recipients": [
      {
        "recipient": "f1444a41-b3af-4e30-8655-9a70de1e0915",
        "type": "subscriber_id",
        "notification_id": "9b2e0c0e-5c1f-4a39-9d55-0d6c1e2f7a10"
      }
    ],
    "rejected_recipients": [
      {
        "recipient": "0c7d9f2a-6a1e-4b6e-9c3a-2f5e8d7a6b10",
        "type": "subscriber_id",
        "error_code": "SUBSCRIBER_NOT_FOUND"
      },
      {
        "recipient": "3e8a1b6c-7d2f-4d7f-8a9b-1c2d3e4f5a60",
        "type": "subscriber_id",
        "error_code": "PUSH_TOKEN_EXPIRED"
      }
    ]
  },
  "errors": false
}

ناموفق‌شدن پس از پذیرش (failure_code)

پاسخ 200 یعنی پیام در صف ارسال قرار گرفته است، نه اینکه حتماً تحویل شده باشد. اگر Firebase بعداً ارسال را رد کند، وضعیت اعلان در check-notification-status و در وب‌هوک تحویل به <code>failed</code> تغییر می‌کند و فیلد <code>failure_code</code> علت را مشخص می‌کند. توکنی که Firebase منقضی اعلام کند در پوشفا غیرفعال می‌شود و ارسال بعدی به همان مخاطب از همان ابتدا خطای <code>PUSH_TOKEN_EXPIRED</code> می‌گیرد.

نمونه خطای اعتبارسنجی

در <code>VALIDATION_ERROR</code> فیلد <code>errors</code> برای هر فیلد نامعتبر فهرست پیام‌ها را دارد.

{
  "message": "فیلد عنوان الزامی است",
  "status_code": -1,
  "error_code": "VALIDATION_ERROR",
  "data": [],
  "errors": {
    "title": ["فیلد عنوان الزامی است"]
  }
}