رابط برنامهنویسی کاربردی جیمیل دو سطح از اطلاعات خطا را برمیگرداند:
- کدهای خطای HTTP و پیامهای موجود در هدر.
- یک شیء JSON در بدنه پاسخ با جزئیات اضافی که میتواند به شما در تعیین نحوه مدیریت خطا کمک کند.
برنامه Gmail شما باید تمام خطاهایی را که هنگام استفاده از REST API با آنها مواجه میشوید، دریافت و مدیریت کند. این راهنما دستورالعملهایی در مورد نحوه رفع خطاهای خاص Gmail API ارائه میدهد.
خلاصه کد وضعیت HTTP
| کد خطا | توضیحات |
|---|---|
200 - OK | درخواست موفقیتآمیز است (این پاسخ استاندارد برای درخواستهای موفق HTTP است). |
400 - Bad Request | به دلیل خطای کلاینت، سرور نتوانست درخواست را انجام دهد. |
401 - Unauthorized | درخواست شامل اعتبارنامههای نامعتبر است. |
403 - Forbidden | سرور درخواست را دریافت و متوجه شده است، اما کاربر مجوز انجام درخواست را ندارد. |
404 - Not Found | منبع مورد نظر یافت نشد. |
429 - Too Many Requests | درخواستهای زیادی به API ارسال میشود. |
500, 502, 503, 504 - Server Errors | هنگام پردازش درخواست، خطای غیرمنتظرهای رخ داد. |
۴۰۰ خطا
این خطاها به این معنی است که درخواست دارای خطا است، که اغلب به دلیل عدم وجود پارامتر مورد نیاز است.
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
این خطا زمانی رخ میدهد که سیاست دامنه کاربر به برنامه شما اجازه دسترسی به 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."
}
}
برای رفع این خطا، موارد زیر را امتحان کنید:
- به کاربر اطلاع دهید که دامنه به برنامه شما اجازه دسترسی به Gmail را نمیدهد.
- به کاربر دستور دهید تا برای درخواست دسترسی به برنامه شما با مدیر دامنه خود تماس بگیرد.
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، مشترک است. اگر از این محدودیتها تجاوز کنید، API خطای HTTP 429 "درخواستهای زیادی وجود دارد: محدودیت نرخ کاربر از حد مجاز فراتر رفت (ارسال ایمیل)" را با زمان تلاش مجدد برمیگرداند. تجاوز از محدودیتهای روزانه ممکن است منجر به این خطاها برای چندین ساعت قبل از پذیرش درخواست توسط سرور شود.
فرآیند ارسال ایمیل پیچیده است: به محض اینکه کاربر از سهمیه خود فراتر رود، ممکن است چند دقیقه طول بکشد تا API شروع به بازگرداندن پاسخهای خطای ۴۲۹ کند. نمیتوانید فرض کنید که پاسخ ۲۰۰ به معنای ارسال موفقیتآمیز ایمیل است.
محدودیتهای پهنای باند
این API محدودیتهای پهنای باند آپلود و دانلود برای هر کاربر دارد که برابر با IMAP اما مستقل از آن است. این محدودیتها برای یک کاربر در بین همه کلاینتهای Gmail API به اشتراک گذاشته میشود.
کاربران معمولاً فقط در شرایط استثنایی یا سوءاستفاده با این محدودیتها مواجه میشوند. اگر از این محدودیتها تجاوز کنید، API خطای HTTP 429 "درخواستهای زیادی وجود دارد: از حد مجاز نرخ کاربر فراتر رفته است" را با زمان تلاش مجدد برمیگرداند. تجاوز از محدودیتهای روزانه ممکن است منجر به این خطاها برای چندین ساعت قبل از پذیرش درخواست توسط سرور شود.
درخواستهای همزمان
رابط برنامهنویسی کاربردی (API) جیمیل، محدودیت درخواست همزمان برای هر کاربر (علاوه بر محدودیت نرخ برای هر کاربر) را اعمال میکند. این محدودیت بین تمام کلاینتهای API جیمیل که به یک کاربر دسترسی دارند، به اشتراک گذاشته میشود و تضمین میکند که هیچ کلاینت API، صندوق پستی کاربر جیمیل یا سرور پشتیبان او را بیش از حد بارگذاری نکند.
ارسال درخواستهای موازی زیاد برای یک کاربر یا ارسال دستهای از درخواستها با تعداد زیاد میتواند باعث بروز این خطا شود. دسترسی همزمان تعداد زیادی از کلاینتهای API مستقل به صندوق پستی کاربر Gmail نیز میتواند باعث بروز این خطا شود. اگر از این حد تجاوز کنید، API خطای HTTP 429 "درخواستهای بسیار زیاد: درخواستهای همزمان برای کاربر بسیار زیاد است" را برمیگرداند.
خطاهای ۵۰۰، ۵۰۲، ۵۰۳، ۵۰۴
این خطاها زمانی رخ میدهند که هنگام پردازش درخواست، یک خطای غیرمنتظره از سمت سرور رخ دهد. مسائل مختلفی میتوانند باعث این خطاها شوند، از جمله همپوشانی زمانبندی یک درخواست با درخواست دیگر یا درخواست برای یک اقدام پشتیبانی نشده، مانند تلاش برای بهروزرسانی مجوزها برای یک صفحه واحد در Google Sites به جای کل سایت.
لیست خطاهای 5xx به شرح زیر است:
- خطای ۵۰۰ در پنل مدیریت
- ۵۰۲ دروازه خراب
- کد خطای ۵۰۳: سرویس در دسترس نیست
- وقفه زمانی ۵۰۴ در دروازه
backendError
این خطا زمانی رخ میدهد که هنگام پردازش درخواست، خطای غیرمنتظرهای رخ دهد. نمونه JSON زیر، نمونهای از این خطا است:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
برای رفع این خطا، از تابع برگشت نمایی (exponential backoff) برای تکرار درخواست استفاده کنید.
برای رفع خطاها، درخواستهای ناموفق را دوباره امتحان کنید
شما میتوانید به صورت دورهای یک درخواست ناموفق را در مدت زمان فزایندهای دوباره امتحان کنید تا خطاهای مربوط به محدودیتهای سرعت، حجم شبکه یا زمان پاسخ را مدیریت کنید. به عنوان مثال، ممکن است یک درخواست ناموفق را پس از یک ثانیه، سپس پس از دو ثانیه و سپس پس از چهار ثانیه دوباره امتحان کنید. این روش، backoff نمایی نامیده میشود و برای بهبود استفاده از پهنای باند و به حداکثر رساندن توان عملیاتی درخواستها در محیطهای همزمان استفاده میشود.
دورههای تلاش مجدد را حداقل یک ثانیه پس از خطا شروع کنید.
مدیریت محدودیتهای سهمیه
برای مشاهده یا تغییر محدودیتهای استفاده برای پروژه خود یا درخواست افزایش سهمیه خود، موارد زیر را انجام دهید:
- اگر هنوز برای پروژه خود حساب کاربری ندارید، یکی ایجاد کنید.
- به صفحه APIهای فعالشده در کتابخانه API در کنسول API مراجعه کنید و یک API را از لیست انتخاب کنید.
- برای مشاهده و تغییر تنظیمات مربوط به سهمیه، گزینه سهمیهها (Quotas) را انتخاب کنید. برای مشاهده آمار استفاده، گزینه استفاده (Usage) را انتخاب کنید.
برای اطلاعات بیشتر، به «مشاهده و مدیریت سهمیهها» مراجعه کنید.
درخواستهای دستهای
درخواستهای دستهای میتوانند عملکرد را بهبود بخشند، اما اندازههای بزرگتر دسته میتوانند باعث محدودیت سرعت شوند. دستههای بزرگتر از ۵۰ درخواست ارسال نکنید. برای اطلاعات بیشتر در مورد نحوه دسته بندی درخواستها، به درخواستهای دستهای مراجعه کنید.