رفع خطاها

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

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

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

رفع خطای ۴۰۰: درخواست نادرست

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

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

توجه: این لیست کامل نیست، موارد دیگر نیز می‌توانند باعث خطای ۴۰۰ شوند.

در زیر نمونه‌ای از نمایش 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 را بررسی کرده و کد خود را متناسب با آن تنظیم کنید.

رفع خطای ۴۰۱: اعتبارنامه‌های نامعتبر

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

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

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

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

رفع خطای ۴۰۳: محدودیت استفاده از حد مجاز فراتر رفته است

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

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

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

رفع خطای ۴۰۳: محدودیت روزانه بیش از حد مجاز است

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

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

برای رفع این خطا:

1. از کنسول API گوگل دیدن کنید
2. پروژه خود را انتخاب کنید.
3. روی برگه سهمیه‌ها کلیک کنید
4. درخواست سهمیه اضافی. برای اطلاعات بیشتر، به درخواست سهمیه اضافی مراجعه کنید.

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

رفع خطای ۴۰۳: محدودیت نرخ کاربر فراتر رفته است

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

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

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

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

رفع خطای ۴۰۳: محدودیت سرعت از حد مجاز فراتر رفت

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

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

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

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

رفع خطای ۴۰۳: برنامه‌ای با شناسه {appId} نمی‌تواند در دامنه کاربر احراز هویت شده استفاده شود

خطای 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. به کاربر دستور دهید تا برای درخواست دسترسی به برنامه شما با مدیر دامنه تماس بگیرد.

رفع خطای ۴۲۹: درخواست‌های زیاد

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

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

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

این محدودیت‌ها برای هر کاربر است و بین همه کلاینت‌های کاربر، چه کلاینت‌های API، کلاینت‌های native/web یا SMTP MSA، مشترک است. اگر از این محدودیت‌ها تجاوز شود، خطای HTTP 429 Too Many Requests "User-rate limit exceeded" "(Mail sending)" با زمان تلاش مجدد بازگردانده می‌شود. توجه داشته باشید که تجاوز از محدودیت‌های روزانه ممکن است منجر به این نوع خطاها برای چندین ساعت قبل از پذیرش درخواست شود.

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

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

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

این محدودیت‌ها معمولاً فقط در شرایط استثنایی یا سوءاستفاده اعمال می‌شوند. اگر از این محدودیت‌ها تجاوز شود، خطای HTTP 429 Too Many Requests "User-rate limit exceeded" به همراه زمان تلاش مجدد بازگردانده می‌شود. توجه داشته باشید که تجاوز از محدودیت‌های روزانه ممکن است منجر به این نوع خطاها برای چندین ساعت قبل از پذیرش درخواست شود.

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

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

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

رفع خطای ۵۰۰: خطای بک‌اند

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

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

برای رفع این خطا، درخواست‌های ناموفق را دوباره امتحان کنید . در زیر لیستی از خطاهای ۵۰۰ آمده است:

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

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

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

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

مشاهده یا تغییر محدودیت‌های استفاده، افزایش سهمیه

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

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

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

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