مرجع خطاها

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

معنی error_code و HTTP status وب‌سرویس‌های ارسال پوشفا را ببینید و بفهمید چه زمانی توکن منقضی یا subscriber_id ناموجود را از پایگاه داده خود حذف کنید.

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

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

برای سازگاری با نسخه‌های قبلی، در همه خطاها status_code برابر -1 و errors برابر true باقی مانده است. فقط در خطای اعتبارسنجی (VALIDATION_ERROR) فیلد errors به‌جای true فهرست خطای هر فیلد را دارد.
{
  "message": "توکن Push این مشترک منقضی یا باطل شده است.",
  "status_code": -1,
  "error_code": "PUSH_TOKEN_EXPIRED",
  "data": { "recipient": "f1444a41-b3af-4e30-8655-9a70de1e0915", "type": "subscriber_id" },
  "errors": true
}

کد HTTP و عنوان متنی آن چه می‌گویند؟

کد HTTP نتیجه کلی درخواست را مشخص می‌کند؛ عنوان انگلیسی زیر نام رایج همان وضعیت است و با متن فارسی message در بدنه پاسخ تفاوت دارد. علت دقیق را از error_code بخوانید. برای نمونه، 422 می‌تواند هم خطای ورودی باشد و هم نداشتن اشتراک پوش؛ بنابراین فقط از روی عدد HTTP وضعیت مشترک را تغییر ندهید.

HTTPعنوان وضعیتمعنی در وب‌سرویس ارسال پوشفا
200 OK — درخواست پذیرفته شد پیام برای گیرندگان پذیرفته‌شده در صف است؛ تحویل قطعی نیست و در ارسال چندگیرنده‌ای rejected_recipients را هم بررسی کنید.
401 Unauthorized — احراز هویت نامعتبر کلید عمومی یا خصوصی سرویس معتبر نیست.
402 Payment Required — اعتبار ناکافی موجودی کیف پول برای ارسال کافی نیست.
403 Forbidden — دسترسی غیرمجاز حساب، سرویس، IP یا قابلیت درخواستی اجازه این عملیات را نمی‌دهد.
404 Not Found — مقصد پیدا نشد شناسه مشترک، توکن، Alias یا تاپیک در سرویس موردنظر وجود ندارد.
410 Gone — اشتراک نامعتبر شده توکن پوش مشترک منقضی یا باطل شده است؛ لغو مجوز فقط یکی از علت‌های ممکن است.
422 Unprocessable Entity — درخواست قابل پردازش نیست ورودی نامعتبر، زمان ارسال نامعتبر، نبود اشتراک فعال یا برقرارنبودن شرط مخاطب؛ علت دقیق در error_code است.
429 Too Many Requests — محدودیت تعداد نرخ درخواست یا سقف Frequency Cap رعایت نشده است.
500 Internal Server Error — خطای داخلی سرور پردازش درخواست با خطای غیرمنتظره مواجه شده است.

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

ستون message متن فارسی پیش‌فرض هر خطاست. بعضی مسیرها پیام دقیق‌تری برمی‌گردانند؛ به‌ویژه در VALIDATION_ERROR متن message و errors به فیلد نامعتبر بستگی دارد. مقایسه متن پیام را مبنای منطق برنامه قرار ندهید.

HTTPerror_codeمتن پیام (message)علتاقدام پیشنهادی
422 VALIDATION_ERROR اطلاعات ارسالی معتبر نیست. فیلدی ناقص یا نامعتبر است؛ مثلاً title خالی است، subscriber_id قالب UUID ندارد، subscriber_id و fcm_token هم‌زمان ارسال شده‌اند یا last_visit عملگر یا تاریخ نامعتبر (مثلاً تاریخ شمسی) دارد. خطای هر فیلد در errors آمده است. ورودی را اصلاح کنید و دوباره بفرستید.
401 INVALID_API_KEYS کلید عمومی یا کلید خصوصی سرویس معتبر نیست. api_public_key و api_private_key با هیچ سرویسی مطابقت ندارند. کلیدها را دوباره از پنل همین سرویس کپی کنید؛ تکرار درخواست بدون اصلاح فایده‌ای ندارد.
403 ACCOUNT_BLOCKED حساب کاربری مالک این سرویس مسدود است. حساب کاربری مالک سرویس مسدود است. با پشتیبانی پوشفا تماس بگیرید.
403 SERVICE_INACTIVE این سرویس غیرفعال است. برای ارسال نوتیفیکیشن ابتدا یک دامنه به آن اختصاص دهید. سرویس غیرفعال است؛ معمولاً چون دامنه‌ای به آن اختصاص داده نشده است. در پنل یک دامنه به سرویس اختصاص دهید.
403 IP_NOT_ALLOWED دسترسی به وب‌سرویس از این IP مجاز نیست. IP سرور شما در فهرست IPهای مجاز وب‌سرویس این سرویس نیست. IP سرور را در تنظیمات سرویس اضافه کنید یا درخواست را از سرور مجاز بفرستید.
403 COLLAPSE_ID_DISABLED قابلیت Collapse ID توسط مدیر غیرفعال شده است. قابلیت collapse_id توسط مدیر پوشفا غیرفعال شده است. collapse_id را از درخواست حذف کنید.
403 LAST_VISIT_TRACKING_DISABLED ثبت آخرین بازدید برای این سرویس غیرفعال است و only_last_device قابل استفاده نیست. برای شرط last_visit: ثبت آخرین بازدید برای این سرویس غیرفعال است و شرط last_visit قابل استفاده نیست. only_last_device یا شرط last_visit ارسال شده، اما ثبت آخرین بازدید برای این سرویس خاموش است. ثبت آخرین بازدید را در تنظیمات سرویس روشن کنید یا only_last_device و last_visit را نفرستید.
422 INVALID_SEND_TIME زمان ارسال واردشده معتبر نیست. در ارسال زمان‌بندی‌شده، time گذشته یا همین لحظه است. time را به تاریخ میلادی با قالب Y-m-d H:i و ساعت تهران (Asia/Tehran)، برای زمانی بعد از اکنون بفرستید. زمان گذشته یا همین لحظه پیش از ثبت پیام و کسر اعتبار رد می‌شود.
402 INSUFFICIENT_BALANCE موجودی کیف پول برای این ارسال کافی نیست. اعتبار کیف پول برای حداکثر هزینه این ارسال کافی نیست. کیف پول را شارژ کنید و دوباره بفرستید.
429 RATE_LIMIT_EXCEEDED تعداد درخواست‌ها بیش از حد مجاز است؛ کمی بعد دوباره تلاش کنید. تعداد درخواست‌های شما در بازه زمانی کوتاه بیش از حد مجاز است. با فاصله و Backoff دوباره تلاش کنید؛ سرآیند Retry-After زمان انتظار را مشخص می‌کند.
500 INTERNAL_ERROR خطای داخلی سرور رخ داد؛ کمی بعد دوباره تلاش کنید. خطای غیرمنتظره در سرور پوشفا رخ داده است. کمی بعد دوباره تلاش کنید و اگر تکرار شد به پشتیبانی اطلاع دهید.

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

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

HTTPerror_codeمتن پیام (message)یعنی چهبا شناسه چه کنید
404 SUBSCRIBER_NOT_FOUND مشترکی با این شناسه در این سرویس وجود ندارد. این subscriber_id در این سرویس وجود ندارد: اشتباه است، متعلق به سرویس دیگری است، یا مشترک حذف شده است (حذف از پنل، ادغام پروفایل‌ها یا پاک‌سازی خودکار پروفایل‌های بدون Push). push_active = false؛ شناسه ناموجود را پس از بررسی سرویس، از فهرست ارسال حذف یا بایگانی کنید. پس از بازگشت کاربر شناسه معتبر برگشتی SDK را ذخیره کنید.
404 FCM_TOKEN_NOT_FOUND این توکن در این سرویس ثبت نیست یا با توکن جدیدتری جایگزین شده است. این توکن در این سرویس ثبت نیست: اشتباه است، با توکن جدیدتری جایگزین شده (چرخش توکن)، یا پروفایل آن حذف شده است. توکن را حذف کنید و برای این مخاطب از subscriber_id استفاده کنید که با چرخش توکن تغییر نمی‌کند.
410 PUSH_TOKEN_EXPIRED توکن Push این مشترک منقضی یا باطل شده است. مشترک وجود دارد، اما Firebase توکن Push او را منقضی یا نامعتبر اعلام کرده است؛ مثلاً کاربر اجازه اعلان را لغو کرده، داده‌های مرورگر را پاک کرده یا اپ را حذف کرده است. اگر fcm_token فرستاده‌اید آن را حذف کنید. subscriber_id را می‌توانید نگه دارید، اما تا فعال‌شدن دوباره Push به آن ارسال نکنید؛ وضعیت را با وب‌سرویس subscribers/state بررسی کنید.
422 PUSH_NOT_SUBSCRIBED این مشترک هنوز اجازه دریافت اعلان Push نداده است. پروفایل مشترک وجود دارد، اما هنوز اجازه دریافت اعلان نداده و توکن Push ندارد. شناسه را نگه دارید و push_active = false کنید؛ پس از ثبت موفق اشتراک دوباره فعال کنید.
404 ALIAS_NOT_FOUND هیچ مشترکی با این شناسه مستعار (alias) در این سرویس وجود ندارد. هیچ مشترکی در این سرویس با این alias ثبت نشده است. مقدار alias را بررسی کنید و مطمئن شوید setUserAliasID یا وب‌سرویس alias/set برای این کاربر اجرا شده است.
404 CUSTOM_ALIAS_NOT_FOUND هیچ مشترکی با این برچسب و مقدار شناسه سفارشی در این سرویس وجود ندارد. هیچ مشترکی شناسه سفارشی با این label و value ندارد. label و values را بررسی کنید و مطمئن شوید addAlias یا وب‌سرویس aliases/add اجرا شده است.
404 TOPIC_NOT_FOUND تاپیک انتخابی در این سرویس وجود ندارد. تاپیکی با این UUID در این سرویس وجود ندارد. UUID تاپیک را از پنل همین سرویس بردارید.
422 NO_ACTIVE_PUSH_SUBSCRIPTION مقصد انتخابی هیچ دستگاهی با عضویت Push فعال ندارد. مقصد (alias، شناسه سفارشی یا تاپیک) وجود دارد، اما هیچ دستگاه آن عضویت Push فعال ندارد. مقصد را حذف نکنید؛ بعداً دوباره تلاش کنید یا از کانال دیگری مانند پیامک استفاده کنید.
422 NO_MATCHING_DEVICE هیچ دستگاهی با فیلترهای انتخاب‌شده مطابقت ندارد. دستگاه فعال وجود دارد، اما با فیلتر device یا platform درخواست مطابقت ندارد. فیلتر را تغییر دهید یا حذف کنید.
422 LAST_VISIT_CONDITION_NOT_MET آخرین بازدید مخاطب با شرط last_visit درخواست مطابقت ندارد. مخاطب یا دستگاه فعال وجود دارد، اما روز آخرین بازدیدش با شرط last_visit درخواست نمی‌خواند یا هنوز بازدیدی از او ثبت نشده است. در خطای کل درخواست، شرط اعمال‌شده همراه تاریخ محاسبه‌شده در data.last_visit برمی‌گردد. شناسه را حذف نکنید؛ این فقط نتیجه شرط انتخابی شماست. شرط را تغییر دهید یا بدون last_visit بفرستید.
429 FREQUENCY_CAP_REACHED همه مشترکین انتخاب‌شده به سقف Frequency Cap این سرویس رسیده‌اند. گیرنده به سقف Frequency Cap این سرویس رسیده است؛ اگر کل درخواست با این کد رد شود، همه گیرندگان به سقف رسیده‌اند. پس از پایان بازه سقف دوباره بفرستید یا سقف را در تنظیمات سرویس تغییر دهید.
422 NO_VALID_RECIPIENTS هیچ‌کدام از گیرندگان قابل ارسال نیستند؛ علت هر مورد در rejected_recipients آمده است. در ارسال چندگیرنده‌ای هیچ گیرنده‌ای قابل ارسال نبود و علت رد گیرنده‌ها یکسان نبود. علت هر شناسه را در data.rejected_recipients ببینید و طبق همین جدول عمل کنید.

چه زمانی push_active را false کنیم؟

این تصمیم برای همان subscriber_id و همان سرویس است، نه تمام دستگاه‌های کاربر. هنگام ارسال فقط رکوردهای push_active = true را انتخاب کنید. اگر خطای مشخص اشتراک دریافت شد، رکورد را غیرفعال کنید و ارسال‌های بعدی به آن را متوقف کنید. تا ثبت موفق دوباره اشتراک، آن را صرفاً با گذشت زمان یا دریافت HTTP 200 فعال نکنید.

هر 404، 410 یا 422 را به همه مشترکان تعمیم ندهید. TOPIC_NOT_FOUND یا ALIAS_NOT_FOUND دلیل غیرفعال‌کردن subscriber_id نیست؛ NO_MATCHING_DEVICE، LAST_VISIT_CONDITION_NOT_MET و FREQUENCY_CAP_REACHED هم به معنی لغو عضویت نیستند. در پاسخ گروهی، فقط شناسه‌های ردشده با کد مشخصِ اشتراک را تغییر دهید؛ حتی اگر HTTP پاسخ 200 باشد.
HTTP + error_codeمتن پیام برای این حالتاقدام در دیتابیس سایت شما
404 / SUBSCRIBER_NOT_FOUND مشترکی با این شناسه در این سرویس وجود ندارد. push_active = false؛ پس از بررسی سرویس و شناسه، مقصد ناموجود را از فهرست ارسال حذف یا بایگانی کنید.
410 / PUSH_TOKEN_EXPIRED توکن Push این مشترک منقضی یا باطل شده است. push_active = false؛ subscriber_id را برای فعال‌سازی مجدد نگه دارید.
422 / PUSH_NOT_SUBSCRIBED این مشترک هنوز اجازه دریافت اعلان Push نداده است. push_active = false؛ تا ثبت موفق توکن ارسال نکنید.
سایر خطاها، مانند 422 / VALIDATION_ERROR اطلاعات ارسالی معتبر نیست. وضعیت اشتراک را تغییر ندهید؛ ورودی یا علت همان خطا را اصلاح کنید.

نمونه بک‌اند Laravel: رسیدگی به خطای تکی و گروهی

این نمونه را در سرور سایت خود، بعد از دریافت پاسخ ارسال اجرا کنید. $response پاسخ Laravel HTTP Client است؛ $sentSubscriberIds فقط شناسه‌های درخواست فعلی و $serviceId سرویس همان درخواست در دیتابیس شماست. جدول push_subscribers و ستون‌های آن نمونه‌اند و باید با ساختار سایت خود تطبیقشان دهید. برای خطای تکی، HTTP و error_code با هم بررسی می‌شوند؛ در پاسخ چندگیرنده‌ای، علت هر شناسه از rejected_recipients خوانده می‌شود.

در روش قدیمی fcm_token، خطای FCM_TOKEN_NOT_FOUND به همان توکن مربوط است؛ آن را حذف یا غیرفعال کنید و وضعیت همه شناسه‌های کاربر را تغییر ندهید. برای ارسال‌های بعدی، subscriber_id پایدار را نگه دارید.
use Illuminate\Support\Facades\DB;

$subscriptionErrors = [
    'SUBSCRIBER_NOT_FOUND' => 404,
    'PUSH_TOKEN_EXPIRED' => 410,
    'PUSH_NOT_SUBSCRIBED' => 422,
];

// در پاسخ گروهی، این فهرست حتی با HTTP 200 هم باید بررسی شود.
$rejected = $response->json('data.rejected_recipients') ?? [];
$code = $response->json('error_code');
if (!$response->successful()
    && isset($subscriptionErrors[$code])
    && $response->status() === $subscriptionErrors[$code]
    && $response->json('data.type') === 'subscriber_id') {
    $rejected[] = [
        'recipient' => $response->json('data.recipient'),
        'type' => 'subscriber_id',
        'error_code' => $code,
    ];
}

foreach ($rejected as $item) {
    if (($item['type'] ?? null) !== 'subscriber_id'
        || !isset($subscriptionErrors[$item['error_code'] ?? ''])
        || !in_array($item['recipient'] ?? null, $sentSubscriberIds, true)) {
        continue;
    }

    DB::table('push_subscribers')
        ->where('service_id', $serviceId)
        ->where('subscriber_id', $item['recipient'])
        ->update([
            'push_active' => false,
            'last_push_error_code' => $item['error_code'],
            'updated_at' => now(),
        ]);
}

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

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

کداگر fcm_token فرستاده‌ایداگر subscriber_id فرستاده‌اید
FCM_TOKEN_NOT_FOUND حذف کنید؛ برای ارسال‌های بعدی subscriber_id را ذخیره کنید. —
SUBSCRIBER_NOT_FOUND — غیرفعال کنید و از فهرست ارسال حذف یا بایگانی کنید.
PUSH_TOKEN_EXPIRED حذف کنید. نگه دارید، اما تا فعال‌شدن دوباره Push ارسال نکنید.
INVALID_PUSH_TOKEN حذف کنید. نگه دارید، اما تا ثبت توکن معتبر جدید ارسال نکنید.
PUSH_NOT_SUBSCRIBED — نگه دارید و push_active = false کنید؛ پس از ثبت موفق اشتراک دوباره فعال کنید.
NO_MATCHING_DEVICE، LAST_VISIT_CONDITION_NOT_MET، FREQUENCY_CAP_REACHED نگه دارید. نگه دارید.

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

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

پیش از این، اگر حتی یک شناسه نامعتبر در send-group-message بود، کل درخواست با خطای 422 رد می‌شد. اکنون گیرندگان معتبر پیام را دریافت می‌کنند و هزینه فقط برای همان‌ها کسر می‌شود.
{
  "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 و در وب‌هوک تحویل به failed تغییر می‌کند و فیلد failure_code علت را مشخص می‌کند. توکنی که Firebase منقضی اعلام کند در پوشفا غیرفعال می‌شود و ارسال بعدی به همان مخاطب از همان ابتدا خطای PUSH_TOKEN_EXPIRED می‌گیرد.

failure_codeعلتاقدام پیشنهادی
PUSH_TOKEN_EXPIRED Firebase توکن را ثبت‌نشده یا منقضی اعلام کرده است. fcm_token را حذف کنید؛ subscriber_id را نگه دارید و push_active = false کنید تا اشتراک دوباره فعال شود.
INVALID_PUSH_TOKEN Firebase قالب توکن را نامعتبر می‌داند. fcm_token را حذف کنید؛ subscriber_id را نگه دارید و تا ثبت توکن معتبر جدید push_active = false کنید.
FIREBASE_AUTH_ERROR اعتبارنامه Firebase سرویس معتبر نیست یا توکن متعلق به پروژه Firebase دیگری است. تنظیمات Firebase و Service Account سرویس را بررسی کنید؛ توکن را حذف نکنید.
MESSAGE_REJECTED Firebase محتوای پیام را نپذیرفته است؛ مثلاً حجم یا قالب داده نامعتبر است. محتوا و additional_data را کوتاه‌تر یا اصلاح کنید.
INSUFFICIENT_BALANCE در لحظه ارسال (مثلاً در ارسال زمان‌بندی‌شده) اعتبار کیف پول کافی نبوده است. کیف پول را شارژ کنید و دوباره بفرستید.
SEND_FAILED سایر خطاهای ارسال، از جمله خطای موقت Firebase که پس از تلاش مجدد هم برطرف نشده است. دوباره ارسال کنید؛ توکن را حذف نکنید.

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

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

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