Errors & Troubleshooting

خطاها و رفع مشکل

راهنمای خطاهای رایج Messaging API نویدا، کدهای خطا، دلایل احتمالی و روش رفع آن‌ها.

خطاها و رفع مشکل

در صورت نامعتبر بودن درخواست یا بروز مشکل در فرآیند ارسال، Messaging API نویدا خطا را با یک ساختار استاندارد برمی‌گرداند.

نمونه پاسخ:

{
  "error": {
    "code": "template_parameters_mismatch",
    "message": "Template parameters must exactly match the template placeholders.",
    "details": {
      "template_id": 12,
      "expected": ["name", "order_id"],
      "missing": [],
      "extra": ["foo"]
    }
  },
  "request_id": "..."
}

ساختار خطا

فیلد	توضیح
`code`	شناسه قابل برنامه‌ریزی خطا است.
`message`	توضیح متنی خطا را نمایش می‌دهد.
`details`	در برخی خطاها اطلاعات تکمیلی دارد.
`request_id`	شناسه درخواست است و در زمان پیگیری مشکل می‌تواند برای پشتیبانی مفید باشد.

خطاهای رایج

Code	توضیح	راه‌حل پیشنهادی
`invalid_phone`	شماره گیرنده معتبر نیست	فرمت شماره را بررسی کنید
`message_required`	Message یا Template ارسال نشده است	یکی از این دو را مشخص کنید
`message_too_long`	متن از حد مجاز بیشتر است	طول پیام را کاهش دهید
`channels_required`	کانال ارسال مشخص نشده است	مقدار channels را ارسال کنید
`invalid_strategy`	Strategy نامعتبر است	از failover یا broadcast استفاده کنید
`invalid_delay`	مقدار Delay معتبر نیست	مانند 30m یا 2h ارسال کنید
`schedule_must_be_future`	زمان ارسال در گذشته است	زمان آینده انتخاب کنید
`schedule_too_far`	زمان ارسال بیش از حد مجاز است	زمان را حداکثر تا ۳۰ روز آینده تعیین کنید
`template_not_found`	Template پیدا نشد	شناسه قالب را بررسی کنید
`template_invalid`	قالب قابل استفاده نیست	وضعیت و ساختار قالب را بررسی کنید
`template_parameters_mismatch`	پارامترها با قالب مطابقت ندارند	پارامترها را دقیقاً مطابق قالب ارسال کنید
`channel_unavailable`	کانال در دسترس نیست	وضعیت حساب متصل را بررسی کنید
`channel_ambiguous`	چند حساب فعال وجود دارد و حساب مشخص نیست	Default تعیین کنید یا account_id بفرستید
`channel_account_not_found`	Account پیدا نشد	شناسه حساب را بررسی کنید
`channel_account_mismatch`	Account با Channel مطابقت ندارد	حساب مرتبط با همان کانال را انتخاب کنید
`duplicate_channel`	مسیر تکراری ارسال شده است	Channelهای تکراری را حذف کنید
`sms_message_config_missing`	تنظیمات SMS کامل نیست	تنظیمات حساب SMS و خط ارسال را بررسی کنید
`insufficient_balance`	موجودی کافی نیست	کیف پول را شارژ کنید
`test_key_not_allowed`	از Test Key استفاده شده است	Live API Key استفاده کنید

مشکلات رایج

پیام در وضعیت queued باقی مانده است

ممکن است پیام در صف ارسال یا منتظر زمان برنامه‌ریزی‌شده باشد. مقدار scheduled_for و وضعیت Attemptها را بررسی نمایید.

پیام ارسال نشد اما Request موفق بود

پاسخ 201 Created تنها به معنی پذیرفته شدن درخواست است. نتیجه نهایی را از طریق GET /v1/messages/{message_id} بررسی نمایید.

Failover به کانال بعدی رفته است

اگر Attempt قبلی ناموفق باشد، نویدا طبق ترتیب channels کانال بعدی را امتحان می‌کند.

چند حساب برای یک کانال دارم

در صورت نبود حساب Default، درخواست ممکن است با channel_ambiguous رد شود. یک حساب را Default نمایید یا account_id مشخص کنید.

در زمان تماس با پشتیبانی

در صورت نیاز به بررسی بیشتر، اطلاعات زیر را ارسال نمایید:

request_id
message_id
زمان تقریبی درخواست
کد خطا

از ارسال API Key یا سایر اطلاعات محرمانه خودداری نمایید.