کدهای خطای 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 به فیلد نامعتبر بستگی دارد. مقایسه متن پیام را مبنای منطق برنامه قرار ندهید.
| HTTP | error_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 برمیگردد.
| HTTP | error_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 فعال نکنید.
| 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 خوانده میشود.
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 میآیند. ارسال به تاپیک گزارش جداگانه برای هر مشترک ندارد.
{
"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": ["فیلد عنوان الزامی است"]
}
}