پرش به مطلب اصلی

مدیریت خطاها

این مستند شامل تمام خطاهای ممکن در داشبورد کاربر آپارات و نحوه مدیریت آن‌ها است.

فلسفه مدیریت خطا در آپارات​

اصول کلی​

  1. شفافیت: پیام‌های خطا باید واضح و قابل فهم باشند
  2. راهنمایی: به کاربر بگوییم چطور می‌تواند مشکل را حل کند
  3. دوستانه بودن: از لحن تشویقی و کمک‌کننده استفاده کنیم، نه سرزنش‌کننده
  4. ثبت لاگ: تمام خطاها باید برای تیم فنی لاگ شوند

سطوح خطا​

  • سطح ۱ - اطلاع‌رسانی (Info): پیام‌های ساده که نیاز به اقدام فوری ندارند
  • سطح ۲ - هشدار (Warning): مواردی که ممکن است مشکل‌ساز شوند
  • سطح ۳ - خطا (Error): مشکلاتی که مانع از انجام عملیات می‌شوند
  • سطح ۴ - بحرانی (Critical): خطاهای شدید که نیاز به رسیدگی فوری دارند

دسته‌بندی خطاها​

۱. خطاهای احراز هویت (Authentication Errors)​

۱.۱ کاربر لاگین نکرده​

کد خطا: AUTH_001

شرایط: کاربر تلاش می‌کند به بخشی از داشبورد دسترسی پیدا کند بدون اینکه لاگین کرده باشد.

پیام خطا:

برای دسترسی به این بخش باید وارد حساب کاربری خود شوید.

اقدام سیستم:

  • کاربر را به صفحه لاگین هدایت می‌کند
  • آدرس صفحه فعلی را ذخیره می‌کند تا بعد از لاگین، کاربر به همان صفحه برگردد

API Response:

{
  "error": {
    "code": "AUTH_001",
    "message": "User not authenticated",
    "user_message": "برای دسترسی به این بخش باید وارد حساب کاربری خود شوید.",
    "action": "redirect_to_login"
  }
}

نحوه رفع: کاربر باید لاگین کند.

۱.۲ توکن منقضی شده​

کد خطا: AUTH_002

شرایط: توکن JWT کاربر منقضی شده است.

پیام خطا:

نشست شما منقضی شده است. لطفاً مجدداً وارد شوید.

اقدام سیستم:

  • سعی می‌کند با Refresh Token، توکن جدید بگیرد
  • اگر Refresh Token هم منقضی شده، کاربر را به صفحه لاگین هدایت می‌کند

API Response:

{
  "error": {
    "code": "AUTH_002",
    "message": "Token expired",
    "user_message": "نشست شما منقضی شده است. لطفاً مجدداً وارد شوید.",
    "action": "refresh_or_login"
  }
}

۱.۳ توکن نامعتبر​

کد خطا: AUTH_003

شرایط: توکن ارسال‌شده نامعتبر یا جعلی است.

پیام خطا:

خطا در احراز هویت. لطفاً دوباره وارد شوید.

اقدام سیستم:

  • کاربر را logout می‌کند
  • به صفحه لاگین هدایت می‌کند
  • این رویداد به عنوان مشکوک لاگ می‌شود

۲. خطاهای دسترسی (Authorization Errors)​

۲.۱ کاربر بن شده (Banned User)​

کد خطا: AUTH_101

شرایط: کاربر به دلیل نقض قوانین، تنبیه شده و دسترسی آپلود ندارد.

پیام خطا:

دسترسی شما به آپلود ویدئو مسدود شده است.
دلیل: [دلیل تنبیه]
تاریخ پایان: [تاریخ] یا "دائمی"

برای اطلاعات بیشتر با پشتیبانی تماس بگیرید.

اقدام سیستم:

  • مودال آپلود باز نمی‌شود
  • لینک پشتیبانی نمایش داده می‌شود

API Response:

{
  "error": {
    "code": "AUTH_101",
    "message": "User is banned from uploading",
    "user_message": "دسترسی شما به آپلود ویدئو مسدود شده است.",
    "details": {
      "ban_reason": "نقض حق نشر",
      "ban_end_date": "2024-12-31",
      "is_permanent": false
    },
    "support_link": "https://aparat.com/support"
  }
}

۲.۲ عدم دسترسی به ویژگی خاص​

کد خطا: AUTH_102

شرایط: کاربر تلاش می‌کند از ویژگی‌ای استفاده کند که برای نقش او مجاز نیست (مثلاً مشاهده درآمد در حالی که در سیستم درآمدزایی عضو نیست).

پیام خطا:

برای دسترسی به این بخش، باید در سیستم درآمدزایی آپارات عضو شوید.

[دکمه: درباره درآمدزایی بیشتر بدانید]

اقدام سیستم:

  • بخش مربوطه نمایش داده نمی‌شود یا غیرفعال است
  • لینک راهنما نمایش داده می‌شود

۳. خطاهای ولیدیشن (Validation Errors)​

۳.۱ فیلد الزامی خالی​

کد خطا: VAL_001

شرایط: کاربر فیلدی را که الزامی است، خالی گذاشته.

پیام خطا:

[نام فیلد] الزامی است.

مثال:

عنوان ویدئو الزامی است.

اقدام سیستم:

  • فیلد مربوطه به رنگ قرمز هایلایت می‌شود
  • فرم ارسال نمی‌شود تا کاربر فیلد را پر کند

API Response:

{
  "error": {
    "code": "VAL_001",
    "message": "Required field is empty",
    "field": "title",
    "user_message": "عنوان ویدئو الزامی است."
  }
}

۳.۲ طول فیلد نامعتبر​

کد خطا: VAL_002

شرایط: مقدار فیلد کوتاه‌تر یا بلندتر از حد مجاز است.

پیام خطا - خیلی کوتاه:

[نام فیلد] حداقل باید [تعداد] کاراکتر باشد.

پیام خطا - خیلی بلند:

[نام فیلد] حداکثر می‌تواند [تعداد] کاراکتر باشد.

مثال:

عنوان ویدئو حداقل باید ۳ کاراکتر باشد.
توضیحات حداکثر می‌تواند ۲۰۰۰ کاراکتر باشد.

اقدام سیستم:

  • تعداد کاراکترهای وارد شده و حد مجاز نمایش داده می‌شود
  • مثال: ۱۵ / ۸۰ کاراکتر

۳.۳ فرمت فیلد نامعتبر​

کد خطا: VAL_003

شرایط: فرمت داده وارد شده معتبر نیست.

پیام خطا:

فرمت [نام فیلد] نامعتبر است.

مثال:

برچسب‌ها نمی‌توانند شامل کاراکترهای ویژه باشند.
فایل زیرنویس معتبر نمی‌باشد، لطفاً مجدداً ارسال نمایید.

۳.۴ محدودیت تعداد​

کد خطا: VAL_004

شرایط: تعداد آیتم‌ها از حد مجاز کمتر یا بیشتر است.

پیام خطا:

حداقل [تعداد] [آیتم] باید انتخاب شود.
حداکثر [تعداد] [آیتم] می‌توانید انتخاب کنید.

مثال:

حداقل ۳ برچسب باید برای هر ویدئو انتخاب شود.
حداکثر ۵ لیست پخش می‌توانید انتخاب کنید.

۴. خطاهای آپلود (Upload Errors)​

۴.۱ پسوند فایل غیرمجاز​

کد خطا: UPL_001

شرایط: فایل آپلودی پسوند مجاز ندارد.

پیام خطا:

پسوند فایل شما مجاز نمی‌باشد.

پسوندهای مجاز: MP4, AVI, MOV, MKV, WMV, FLV, WEBM

اقدام سیستم:

  • فایل reject می‌شود
  • لیست پسوندهای مجاز نمایش داده می‌شود

API Response:

{
  "error": {
    "code": "UPL_001",
    "message": "Invalid file extension",
    "user_message": "پسوند فایل شما مجاز نمی‌باشد.",
    "allowed_extensions": ["mp4", "avi", "mov", "mkv", "wmv", "flv", "webm"]
  }
}

۴.۲ حجم فایل بیش از حد مجاز​

کد خطا: UPL_002

شرایط: حجم فایل بیشتر از حد مجاز کاربر است.

پیام خطا:

اندازه فایل بیش از حد مجاز است.

حداکثر مجاز برای شما: [حجم] گیگابایت
حجم فایل شما: [حجم] گیگابایت

[دکمه: ارتقا به اکانت پریمیوم]

اقدام سیستم:

  • فایل reject می‌شود
  • پیشنهاد ارتقا به اکانت پریمیوم داده می‌شود

۴.۳ محدودیت روزانه​

کد خطا: UPL_003

شرایط: کاربر به حد مجاز آپلود روزانه خود رسیده.

پیام خطا:

شما به حداکثر تعداد/حجم آپلود روزانه خود رسیده‌اید.

آپلودهای امروز: [تعداد] / [حد مجاز]
حجم آپلودشده امروز: [حجم] / [حد مجاز]

لطفاً فردا مجدداً تلاش کنید یا به اکانت پریمیوم ارتقا دهید.

اقدام سیستم:

  • تایمر شمارش معکوس تا نیمه‌شب نمایش داده می‌شود
  • پیشنهاد ارتقا به اکانت پریمیوم

API Response:

{
  "error": {
    "code": "UPL_003",
    "message": "Daily upload limit reached",
    "user_message": "شما به حداکثر تعداد/حجم آپلود روزانه خود رسیده‌اید.",
    "details": {
      "uploads_today": 100,
      "max_uploads": 100,
      "size_uploaded_today_mb": 15360,
      "max_size_mb": 15360,
      "reset_time": "2024-11-17T00:00:00Z"
    }
  }
}

۴.۴ ویدئوی تکراری​

کد خطا: UPL_004

شرایط: ویدئویی با همین هش MD5 قبلاً توسط همین کاربر آپلود شده.

پیام خطا:

این ویدئو قبلاً توسط شما در سایت بارگذاری شده است.

[لینک به ویدئوی قبلی]

اقدام سیستم:

  • فایل reject می‌شود
  • لینک ویدئوی قبلی نمایش داده می‌شود

۴.۵ خطای آپلود فایل​

کد خطا: UPL_005

شرایط: در فرآیند آپلود فایل (شبکه، سرور، ...) مشکلی پیش آمده.

پیام خطا:

در فرآیند آپلود ویدئو مشکلی پیش آمده است.
لطفاً مجدداً تلاش کنید.

[دکمه: تلاش مجدد]

اقدام سیستم:

  • کاربر می‌تواند آپلود را از همان نقطه Resume کند
  • یا از ابتدا Retry کند

۴.۶ خطای پردازش (کانورت)​

کد خطا: UPL_006

شرایط: فایل آپلود شده اما در فرآیند پردازش مشکلی پیش آمده.

پیام خطا:

ویدئوی شما آپلود شد اما در پردازش مشکلی پیش آمد.
تیم فنی ما در حال بررسی هستند.

شماره پیگیری: [کد]

می‌توانید با پشتیبانی تماس بگیرید.

اقدام سیستم:

  • ویدئو در وضعیت "در حال پردازش با خطا" قرار می‌گیرد
  • تیم فنی notification دریافت می‌کنند
  • کاربر می‌تواند با شماره پیگیری، وضعیت را چک کند

۵. خطاهای شبکه (Network Errors)​

۵.۱ قطعی اینترنت​

کد خطا: NET_001

شرایط: اینترنت کاربر قطع شده.

پیام خطا:

ارتباط اینترنت شما قطع شده است.
لطفاً اتصال خود را بررسی کنید.

[دکمه: تلاش مجدد]

اقدام سیستم:

  • هر ۵ ثانیه تلاش می‌کند اتصال را بررسی کند
  • وقتی اتصال برقرار شد، به‌صورت خودکار عملیات قبلی را ادامه می‌دهد

۵.۲ Timeout​

کد خطا: NET_002

شرایط: درخواست به سرور زمان زیادی طول کشیده و timeout شده.

پیام خطا:

درخواست شما زمان زیادی طول کشید.
لطفاً دوباره تلاش کنید.

۵.۳ خطای سرور (5xx)​

کد خطا: NET_003

شرایط: سرور با خطای ۵۰۰، ۵۰۲، ۵۰۳ و ... پاسخ داده.

پیام خطا:

در حال حاضر سرورهای ما با مشکل مواجه هستند.
لطفاً چند دقیقه دیگر مجدداً تلاش کنید.

شماره پیگیری: [کد]

اقدام سیستم:

  • خطا به تیم فنی اطلاع داده می‌شود
  • سیستم monitoring alert ارسال می‌کند

۶. خطاهای داده (Data Errors)​

۶.۱ داده یافت نشد (404)​

کد خطا: DATA_001

شرایط: آیتمی که کاربر به دنبال آن است (ویدئو، لیست پخش، ...) وجود ندارد.

پیام خطا:

[آیتم] مورد نظر یافت نشد.

ممکن است حذف شده باشد.

اقدام سیستم:

  • کاربر را به صفحه لیست هدایت می‌کند

۶.۲ داده خراب (Corrupted Data)​

کد خطا: DATA_002

شرایط: داده دریافتی از سرور ساختار معتبری ندارد.

پیام خطا:

در بارگذاری اطلاعات مشکلی پیش آمد.
لطفاً دوباره تلاش کنید.

۷. خطاهای Business Logic​

۷.۱ تعداد لیست‌های پخش بیش از حد​

کد خطا: BIZ_001

شرایط: کاربر تلاش می‌کند لیست پخش جدید بسازد در حالی که ۱۰۰۰ لیست دارد.

پیام خطا:

شما به حداکثر تعداد لیست‌های پخش مجاز رسیده‌اید (۱۰۰۰).

لطفاً برخی از لیست‌های قدیمی را حذف کنید یا ویدئو را به لیست موجود اضافه کنید.

نکته: این خطا به کاربر نمایش داده نمی‌شود. به‌صورت silent لیست جدید ایجاد نمی‌شود.

۷.۲ افزودن به بیش از ۵ لیست پخش​

کد خطا: BIZ_002

شرایط: کاربر تلاش می‌کند ویدئو را به بیش از ۵ لیست پخش اضافه کند.

رفتار سیستم:

  • فقط ۵ لیست اول انتخاب‌شده اضافه می‌شوند
  • هیچ خطایی نمایش داده نمی‌شود

۸. خطاهای امنیتی (Security Errors)​

۸.۱ تلاش مشکوک​

کد خطا: SEC_001

شرایط: سیستم فعالیت مشکوکی (مثل spam، bruteforce، ...) تشخیص داده.

پیام خطا:

به دلیل فعالیت مشکوک، حساب شما موقتاً مسدود شده است.

لطفاً با پشتیبانی تماس بگیرید.

اقدام سیستم:

  • حساب موقتاً (۱۵ دقیقه) مسدود می‌شود
  • تیم امنیتی alert دریافت می‌کنند

۸.۲ CSRF Token نامعتبر​

کد خطا: SEC_002

شرایط: CSRF Token ارسال‌شده نامعتبر است.

پیام خطا:

خطای امنیتی. لطفاً صفحه را رفرش کنید و دوباره تلاش کنید.

۹. خطاهای کاربری (User Errors)​

۹.۱ عدم تایید ایمیل​

کد خطا: USER_001

شرایط: کاربر ایمیل خود را تایید نکرده.

پیام خطا:

برای استفاده از این ویژگی، ابتدا باید ایمیل خود را تایید کنید.

[دکمه: ارسال مجدد ایمیل تایید]

استراتژی نمایش خطاها​

مکان نمایش​

۱. Inline Validation:

  • زیر فیلد مربوطه
  • رنگ قرمز
  • آیکون خطا

۲. Toast Notification:

  • گوشه بالا سمت راست
  • ۵ ثانیه نمایش
  • قابل بستن

۳. Modal:

  • برای خطاهای مهم
  • نیاز به تایید کاربر

۴. Banner:

  • باالی صفحه
  • برای اطلاع‌رسانی‌های کلی

ثبت لاگ خطاها​

اطلاعات لاگ شده​

{
  "timestamp": "2024-11-16T10:30:00Z",
  "error_code": "UPL_002",
  "error_message": "File size exceeded",
  "user_id": 12345,
  "session_id": "abc123",
  "request_id": "req_xyz789",
  "user_agent": "Mozilla/5.0...",
  "ip_address": "1.2.3.4",
  "context": {
    "file_size": 7000000000,
    "max_size": 3000000000,
    "user_tier": "free"
  },
  "stack_trace": "..."
}

پیوست‌ها​

جدول کامل کدهای خطا​

کددستهشرح
AUTH_001احراز هویتکاربر لاگین نکرده
AUTH_002احراز هویتتوکن منقضی شده
AUTH_003احراز هویتتوکن نامعتبر
AUTH_101دسترسیکاربر بن شده
AUTH_102دسترسیعدم دسترسی به ویژگی
VAL_001ولیدیشنفیلد الزامی خالی
VAL_002ولیدیشنطول نامعتبر
VAL_003ولیدیشنفرمت نامعتبر
VAL_004ولیدیشنمحدودیت تعداد
UPL_001آپلودپسوند غیرمجاز
UPL_002آپلودحجم بیش از حد
UPL_003آپلودمحدودیت روزانه
UPL_004آپلودویدئوی تکراری
UPL_005آپلودخطای آپلود
UPL_006آپلودخطای پردازش
NET_001شبکهقطعی اینترنت
NET_002شبکهTimeout
NET_003شبکهخطای سرور
DATA_001دادهیافت نشد
DATA_002دادهداده خراب
BIZ_001Businessتعداد لیست پخش
BIZ_002Businessافزودن به لیست
SEC_001امنیتفعالیت مشکوک
SEC_002امنیتCSRF نامعتبر
USER_001کاربرایمیل تایید نشده

آخرین به‌روزرسانی: ۱۴۰۳/۰۸/۲۶ نویسنده: تیم فنی آپارات