پرش به محتویات

راهنمای خطاها و کدهای وضعیت (Error Handling)

در صورت بروز هرگونه خطای اعتبارسنجی، امنیتی، دسترسی یا سرور، وب‌سرویس CodeMeet Bot API پاسخی با ساختار استاندارد زیر و کد وضعیت HTTP متناسب بازمی‌گرداند:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}

جدول کدهای وضعیت و راه‌حل‌ها

کد وضعیت عنوان خطا علت متداول نحوه رفع و اقدام پیشنهادی
400 Bad Request ورودی نامعتبر، JSON خراب، ارسال دکمه بدون اکشن یا چت نامعتبر بررسی صحت ساختار داده‌ها و انطباق انواع داده با مستندات
401 Unauthorized توکن ربات اشتباه است یا قبلاً با /revoke باطل شده است بررسی توکن ارسالی یا دریافت توکن جدید از طریق @BotFather
403 Forbidden کاربر ربات را استارت نکرده یا ربات در گروه ادمین نیست درخواست از کاربر برای زدن دکمه Start یا ارتقای دسترسی ربات در گروه
404 Not Found متد درخواستی وجود ندارد یا پیام مشخص‌شده یافت نشد بررسی دیکته نام متد در URL و اطمینان از وجود پیام
409 Conflict تداخل وب‌هوک و Polling، یا نام کاربری تکراری فراخوانی deleteWebhook قبل از Polling
413 Request Entity Too Large حجم درخواست بیش از حد مجاز (بزرگتر از ۱ مگابایت) بهینه‌سازی اندازه Payload ارسالی
429 Too Many Requests ارسال بیش از حد مجاز پیام در ثانیه (Rate Limit) مکث و امتحان مجدد بر اساس مقدار parameters.retry_after
502 Bad Gateway قطعی موقت سرور واسط یا پایگاه داده پیاده‌سازی Retry خودکار با Exponential Backoff

خطاهای رایج و پیام‌های دقیق آنها

۱. خطای the user must start the bot first (کد ۴۰۳)

{
  "ok": false,
  "error_code": 403,
  "description": "Forbidden: the user must start the bot first"
}
علت: به دلیل حفظ حریم خصوصی، ربات‌ها اجازه ارسال پیام به کاربرانی که هنوز دکمه Start را نزده‌اند ندارند.

۲. خطای bot must be an administrator (کد ۴۰۳)

علت: ربات تلاش کرده در یک کانال یا سوپرگروه پیامی پین کند یا پیامی بفرستد در حالی که دسترسی ادمین ندارد.

۳. خطای can't parse entities (کد ۴۰۰)

علت: عدم رعایت سینتکس تگ‌های HTML (مانند نبستن تگ <b>) یا استفاده از کاراکترهای ویژه بدون Escape در parse_mode="Markdown".

۴. خطای محدودیت نرخ ارسال (429 Too Many Requests)

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 5",
  "parameters": {
    "retry_after": 5
  }
}
اقدام: برنامه باید حداقل ۵ ثانیه صبر کرده و سپس پیام را دوباره ارسال کند.