رفع خطاها

رابط برنامه‌نویسی کاربردی جیمیل دو سطح از اطلاعات خطا را برمی‌گرداند:

• کدهای خطای HTTP و پیام‌های موجود در هدر.
• یک شیء JSON در بدنه پاسخ با جزئیات اضافی که می‌تواند به شما در تعیین نحوه مدیریت خطا کمک کند.

برنامه Gmail شما باید تمام خطاهایی را که ممکن است هنگام استفاده از REST API با آنها مواجه شوید، دریافت و مدیریت کند. این راهنما دستورالعمل‌هایی در مورد نحوه رفع خطاهای خاص Gmail API ارائه می‌دهد.

خلاصه کد وضعیت HTTP

۴۰۰ خطا

این خطاها به این معنی است که درخواست دارای خطا است، که اغلب به دلیل عدم وجود پارامتر مورد نیاز است.

badRequest

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

• فیلد یا پارامتر مورد نیاز ارائه نشده است.
• مقدار ارائه شده یا ترکیبی از فیلدهای ارائه شده نامعتبر است.
• پیوست نامعتبر است.

نمونه JSON زیر نمایانگر این خطا است:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

برای رفع این خطا، فیلد message را بررسی کرده و کد خود را متناسب با آن تنظیم کنید.

خطاهای ۴۰۱

این خطاها به این معنی است که درخواست حاوی توکن دسترسی معتبری نیست.

authError

این خطا زمانی رخ می‌دهد که توکن دسترسی مورد استفاده شما منقضی شده یا نامعتبر باشد. این خطا همچنین می‌تواند به دلیل عدم وجود مجوز برای محدوده‌های درخواستی ایجاد شود. نمونه JSON زیر نمایانگر این خطا است:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

برای رفع این خطا، توکن دسترسی را با استفاده از توکن به‌روزرسانی طولانی‌مدت به‌روزرسانی کنید. اگر از یک کتابخانه کلاینت استفاده می‌کنید، به‌روزرسانی توکن به طور خودکار انجام می‌شود. در صورت عدم موفقیت، کاربر را از طریق جریان OAuth، همانطور که در بخش «درباره احراز هویت و مجوزدهی بیشتر بدانید» توضیح داده شده است، هدایت کنید.

برای اطلاعات بیشتر در مورد محدودیت‌های Gmail، به محدودیت‌های استفاده مراجعه کنید.

خطاهای ۴۰۳

این خطاها زمانی رخ می‌دهند که از حد مجاز استفاده تجاوز کنید یا کاربر امتیازات لازم را نداشته باشد. برای تعیین علت، فیلد reason JSON برگردانده شده را ارزیابی کنید. این خطا در شرایط زیر رخ می‌دهد:

• برنامه شما نمی‌تواند در دامنه کاربر احراز هویت شده استفاده شود.
• از حد مجاز روزانه تجاوز شد.
• محدودیت نرخ کاربر بیش از حد مجاز بود.
• سقف نرخ پروژه از حد مجاز فراتر رفت.

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

dailyLimitExceeded

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

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

این خطا زمانی ظاهر می‌شود که صاحب برنامه، محدودیت سهمیه‌ای را برای استفاده از یک منبع خاص تعیین کرده باشد. برای رفع این خطا، سهمیه را در پروژه Google Cloud افزایش دهید. برای اطلاعات بیشتر، به مدیریت محدودیت‌های سهمیه مراجعه کنید.

domainPolicy

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

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

برای رفع این خطا، موارد زیر را امتحان کنید:

1. به کاربر اطلاع دهید که دامنه به برنامه شما اجازه دسترسی به Gmail را نمی‌دهد.
2. به کاربر دستور دهید تا برای درخواست دسترسی به برنامه شما با مدیر دامنه خود تماس بگیرد.

rateLimitExceeded

این خطا نشان می‌دهد که کاربر به حداکثر نرخ درخواست Gmail API رسیده است. این محدودیت بسته به نوع درخواست متفاوت است. نمونه JSON زیر نمایانگر این خطا است:

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
    }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
  }
}

برای رفع این خطا، موارد زیر را امتحان کنید:

• درخواست افزایش سهمیه .
• برای تکرار درخواست از روش برگشت نمایی (exponential backoff) استفاده کنید.

userRateLimitExceeded

این خطا زمانی رخ می‌دهد که محدودیت تعداد کاربران به پایان رسیده باشد. نمونه JSON زیر، نمونه‌ای از این خطا است:

{
  "error": {
  "errors": [
    {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
    }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
  }
}

برای رفع این خطا، سعی کنید کد برنامه خود را بهینه کنید تا درخواست‌های کمتری ایجاد شود یا از روش بازگشت نمایی (exponential backoff) برای امتحان مجدد درخواست استفاده کنید.

۴۲۹ خطا

خطای ۴۲۹ "درخواست‌های بسیار زیاد" می‌تواند به دلیل محدودیت‌های روزانه برای هر کاربر (از جمله محدودیت‌های ارسال ایمیل)، محدودیت‌های پهنای باند یا محدودیت درخواست همزمان برای هر کاربر رخ دهد. اطلاعات مربوط به هر محدودیت در ادامه آمده است. با این حال، هر محدودیت را می‌توان با تلاش مجدد برای درخواست‌های ناموفق یا با تقسیم پردازش بین چندین حساب Gmail برطرف کرد.

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

محدودیت‌های ارسال ایمیل

رابط برنامه‌نویسی کاربردی جیمیل (Gmail API) محدودیت‌های استاندارد ارسال ایمیل روزانه را اعمال می‌کند. این محدودیت‌ها برای کاربران پولی Google Workspace و کاربران آزمایشی gmail.com متفاوت است. برای اطلاع از این محدودیت‌ها، به محدودیت‌های ارسال جیمیل در Google Workspace مراجعه کنید.

این محدودیت‌ها برای هر کاربر است و بین همه کلاینت‌های کاربر، چه کلاینت‌های API، کلاینت‌های داخلی یا وب یا SMTP MSA، مشترک است. اگر از این محدودیت‌ها تجاوز شود، خطای HTTP 429 "درخواست‌های زیادی وجود دارد: محدودیت نرخ کاربر از حد مجاز فراتر رفته است (ارسال ایمیل)" با زمان تلاش مجدد بازگردانده می‌شود. تجاوز از محدودیت‌های روزانه ممکن است منجر به این خطاها برای چندین ساعت قبل از پذیرش درخواست شود.

فرآیند ارسال ایمیل پیچیده است: به محض اینکه کاربر از سهمیه خود فراتر رود، ممکن است چند دقیقه طول بکشد تا API شروع به بازگرداندن پاسخ‌های خطای ۴۲۹ کند. نمی‌توانید فرض کنید که پاسخ ۲۰۰ به معنای ارسال موفقیت‌آمیز ایمیل است.

محدودیت‌های پهنای باند

این API محدودیت‌های پهنای باند آپلود و دانلود برای هر کاربر دارد که برابر با IMAP اما مستقل از آن است. این محدودیت‌ها برای یک کاربر در بین همه کلاینت‌های Gmail API به اشتراک گذاشته می‌شود.

این محدودیت‌ها معمولاً فقط در شرایط استثنایی یا سوءاستفاده اعمال می‌شوند. اگر از این محدودیت‌ها تجاوز شود، خطای HTTP 429 "درخواست‌های بسیار زیاد: محدودیت نرخ کاربر فراتر رفته است" با زمان تلاش مجدد بازگردانده می‌شود. تجاوز از محدودیت‌های روزانه ممکن است منجر به این خطاها برای چندین ساعت قبل از پذیرش درخواست شود.

درخواست‌های همزمان

رابط برنامه‌نویسی کاربردی (API) جیمیل، محدودیت درخواست همزمان برای هر کاربر (علاوه بر محدودیت نرخ برای هر کاربر) را اعمال می‌کند. این محدودیت بین تمام کلاینت‌های API جیمیل که به یک کاربر دسترسی دارند، به اشتراک گذاشته می‌شود و تضمین می‌کند که هیچ کلاینت API، صندوق پستی کاربر جیمیل یا سرور پشتیبان او را بیش از حد بارگذاری نکند.

ارسال درخواست‌های موازی زیاد برای یک کاربر یا ارسال دسته‌ای از درخواست‌ها با تعداد زیاد می‌تواند باعث بروز این خطا شود. دسترسی همزمان تعداد زیادی از کلاینت‌های API مستقل به صندوق پستی کاربر Gmail نیز می‌تواند باعث بروز این خطا شود. اگر از این حد تجاوز شود، خطای HTTP 429 "درخواست‌های بسیار زیاد: درخواست‌های همزمان برای کاربر بسیار زیاد است" بازگردانده می‌شود.

خطاهای ۵۰۰، ۵۰۲، ۵۰۳، ۵۰۴

این خطاها زمانی رخ می‌دهند که هنگام پردازش درخواست، یک خطای غیرمنتظره از سمت سرور رخ دهد. مسائل مختلفی می‌توانند باعث این خطاها شوند، از جمله همپوشانی زمان‌بندی یک درخواست با درخواست دیگر یا درخواست برای یک اقدام پشتیبانی نشده، مانند تلاش برای به‌روزرسانی مجوزها برای یک صفحه واحد در Google Sites به جای کل سایت.

لیست خطاهای 5xx به شرح زیر است:

• خطای ۵۰۰ در پنل مدیریت
• ۵۰۲ دروازه بد
• سرویس ۵۰۳ در دسترس نیست
• زمان انقضای دروازه ۵۰۴

خطای backend

این خطا زمانی رخ می‌دهد که هنگام پردازش درخواست، خطای غیرمنتظره‌ای رخ دهد. نمونه JSON زیر، نمونه‌ای از این خطا است:

{
  "error": {
  "errors": [
    {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
    }
  ],
  "code": 500,
  "message": "Backend Error"
  }
}

برای رفع این خطا، از تابع برگشت نمایی (exponential backoff) برای تکرار درخواست استفاده کنید.

برای رفع خطاها، درخواست‌های ناموفق را دوباره امتحان کنید

شما می‌توانید به صورت دوره‌ای یک درخواست ناموفق را در مدت زمان فزاینده‌ای دوباره امتحان کنید تا خطاهای مربوط به محدودیت‌های سرعت، حجم شبکه یا زمان پاسخ را مدیریت کنید. به عنوان مثال، ممکن است یک درخواست ناموفق را پس از یک ثانیه، سپس پس از دو ثانیه و سپس پس از چهار ثانیه دوباره امتحان کنید. این روش، backoff نمایی نامیده می‌شود و برای بهبود استفاده از پهنای باند و به حداکثر رساندن توان عملیاتی درخواست‌ها در محیط‌های همزمان استفاده می‌شود.

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

مدیریت محدودیت‌های سهمیه

برای مشاهده یا تغییر محدودیت‌های استفاده برای پروژه خود یا درخواست افزایش سهمیه خود، موارد زیر را انجام دهید:

1. اگر هنوز برای پروژه خود حساب کاربری ندارید، یکی ایجاد کنید.
2. به صفحه APIهای فعال‌شده در کتابخانه API در کنسول API مراجعه کنید و یک API را از لیست انتخاب کنید.
3. برای مشاهده و تغییر تنظیمات مربوط به سهمیه، گزینه سهمیه‌ها (Quotas) را انتخاب کنید. برای مشاهده آمار استفاده، گزینه استفاده (Usage) را انتخاب کنید.

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

درخواست‌های دسته‌ای

استفاده از درخواست‌های دسته‌ای توصیه می‌شود؛ با این حال، اندازه‌های بزرگتر دسته احتمالاً باعث ایجاد محدودیت سرعت می‌شوند. ارسال دسته‌های بزرگتر از ۵۰ درخواست توصیه نمی‌شود. برای اطلاعات در مورد نحوه دسته بندی درخواست‌ها، به درخواست‌های دسته‌ای مراجعه کنید.

مباحث مرتبط

• بهبود عملکرد
• عیب‌یابی مشکلات احراز هویت و مجوز