رفع خطاها

Gmail API دو سطح از اطلاعات خطا را برمی گرداند:

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

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

رفع خطای 400: درخواست بد

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

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

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

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

رفع خطای 401: اعتبارنامه نامعتبر است

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

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

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

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

رفع خطای 403: از حد مجاز استفاده فراتر رفته است

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

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

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

رفع خطای 403: از حد مجاز روزانه فراتر رفته است

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

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

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

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

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

رفع خطای 403: از حد مجاز کاربر فراتر رفته است

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

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

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

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

رفع خطای 403: از حد مجاز بیشتر شده است

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

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

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

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

رفع خطای 403: برنامه با شناسه {appId} را نمی توان در دامنه کاربر تأیید شده استفاده کرد

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

رفع خطای 429: درخواست های بسیار زیاد

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

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

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

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

خط لوله ارسال نامه پیچیده است: هنگامی که کاربر از سهمیه خود فراتر رود، ممکن است چندین دقیقه تاخیر وجود داشته باشد تا API شروع به بازگشت 429 پاسخ خطا کند. بنابراین نمی توانید فرض کنید که پاسخ 200 به این معنی است که ایمیل با موفقیت ارسال شده است.

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

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

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

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

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

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

رفع خطای 500: خطای Backend

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

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

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

• دروازه بد 502
• 503 خدمات در دسترس نیست
• 504 Gateway Timeout

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

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

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

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

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

1. اگر قبلاً یک حساب صورت‌حساب برای پروژه خود ندارید، آن را ایجاد کنید.
2. از صفحه Enabled APIs کتابخانه API در کنسول API دیدن کنید و یک API را از لیست انتخاب کنید.
3. برای مشاهده و تغییر تنظیمات مربوط به سهمیه، سهمیه را انتخاب کنید. برای مشاهده آمار استفاده، استفاده را انتخاب کنید.

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

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