خطاهای API را مدیریت کنید

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

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

بقیه این صفحه مرجعی از خطاهای تقویم را به همراه راهنمایی در مورد نحوه رسیدگی به آنها در برنامه ارائه می دهد.

ما قویاً توصیه می‌کنیم که مدیریت خطای برنامه خود را در یک محیط واقعی آزمایش کنید .

پیاده سازی عقب نشینی نمایی

مستندات Cloud APIs توضیح خوبی در مورد backoff نمایی و نحوه استفاده از آن با API های Google دارد.

خطاها و اقدامات پیشنهادی

این بخش نمایش کامل JSON از هر خطای فهرست شده و اقدامات پیشنهادی که ممکن است برای رسیدگی به آن انجام دهید را ارائه می دهد.

400: درخواست بد

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

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "timeRangeEmpty",
    "message": "The specified time range is empty.",
    "locationType": "parameter",
    "location": "timeMax",
   }
  ],
  "code": 400,
  "message": "The specified time range is empty."
 }
}

اقدام پیشنهادی: چون این یک خطای دائمی است، دوباره امتحان نکنید. در عوض پیام خطا را بخوانید و درخواست خود را مطابق با آن تغییر دهید.

401: اعتبار نامعتبر

عنوان مجوز نامعتبر است. رمز دسترسی که استفاده می کنید منقضی شده یا نامعتبر است.

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

اقدامات پیشنهادی:

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

403: از حد مجاز نرخ کاربر فراتر رفت

یکی از محدودیت‌های Developer Console رسیده است.

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

اقدامات پیشنهادی:

• مطمئن شوید که برنامه شما از بهترین شیوه های مدیریت سهمیه ها پیروی می کند.
• سهمیه هر کاربر را در پروژه Developer Console افزایش دهید.
• اگر یک کاربر از طرف بسیاری از کاربران یک حساب Google Workspace درخواست های زیادی می کند، از یک حساب سرویس با تفویض اختیار در دامنه و تنظیم پارامتر quotaUser استفاده کنید.
• از عقب نشینی نمایی استفاده کنید.

403: از حد مجاز فراتر رفت

کاربر به حداکثر نرخ درخواست Google Calendar API برای هر تقویم یا هر کاربر تأیید شده رسیده است.

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

اقدام پیشنهادی: خطاهای rateLimitExceeded می‌توانند کدهای خطای 403 یا 429 را برگردانند—در حال حاضر آنها از نظر عملکردی مشابه هستند و باید با استفاده از عقب‌نشینی نمایی به همان روش پاسخ داده شوند. علاوه بر این، مطمئن شوید که برنامه شما از بهترین شیوه های مدیریت سهمیه ها پیروی می کند.

403: از محدودیت های استفاده از تقویم فراتر رفته است

کاربر برای محافظت از کاربران و زیرساخت های Google در برابر رفتارهای توهین آمیز به یکی از محدودیت های تقویم Google رسیده است.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Calendar usage limits exceeded.",
    "reason": "quotaExceeded"
   }
  ],
  "code": 403,
  "message": "Calendar usage limits exceeded."
 }
}

اقدامات پیشنهادی:

• در راهنمای Google Workspace Administrator درباره محدودیت‌های استفاده از تقویم بیشتر بخوانید.

403: برای غیر سازمان دهنده ممنوع است

درخواست به‌روزرسانی رویداد در تلاش است تا یکی از ویژگی‌های رویداد مشترک را در نسخه‌ای تنظیم کند که متعلق به سازمان‌دهنده نیست. ویژگی های مشترک (به عنوان مثال، guestsCanInviteOthers ، guestsCanModify ، یا guestsCanSeeOtherGuests ) را فقط سازمان دهنده می تواند تنظیم کند.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "forbiddenForNonOrganizer",
    "message": "Shared properties can only be changed by the organizer of the event."
   }
  ],
  "code": 403,
  "message": "Shared properties can only be changed by the organizer of the event."
 }
}

اقدامات پیشنهادی:

• اگر از رویدادها: درج ، رویدادها: وارد کردن ، یا رویدادها: به‌روزرسانی استفاده می‌کنید و درخواست شما شامل هیچ ویژگی مشترکی نیست، این معادل تلاش برای تنظیم آن‌ها به مقادیر پیش‌فرض است. به جای آن از رویدادها استفاده کنید: پچ .
• اگر درخواست شما دارای ویژگی‌های مشترک است، مطمئن شوید که فقط در صورت به‌روزرسانی نسخه سازمان‌دهنده، سعی در تغییر این ویژگی‌ها دارید.

404: یافت نشد

منبع مشخص شده یافت نشد. این می تواند در چندین مورد اتفاق بیفتد. در اینجا چند نمونه آورده شده است:

• زمانی که منبع درخواستی (با شناسه ارائه شده) هرگز وجود نداشته است

• هنگام دسترسی به تقویمی که کاربر نمی تواند به آن دسترسی داشته باشد

  { "error": { "errors": [ { "domain": "global", "reason": "notFound", "message": "Not Found" } ], "code": 404, "message": " یافت نشد" } }

اقدام پیشنهادی: از عقب نشینی نمایی استفاده کنید.

409: شناسه درخواستی از قبل وجود دارد

نمونه ای با شناسه داده شده از قبل در فضای ذخیره سازی وجود دارد.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "duplicate",
    "message": "The requested identifier already exists."
   }
  ],
  "code": 409,
  "message": "The requested identifier already exists."
 }
}

اقدام پیشنهادی: اگر می‌خواهید نمونه جدیدی ایجاد کنید، یک شناسه جدید ایجاد کنید، در غیر این صورت از فراخوانی روش به‌روزرسانی استفاده کنید.

409: درگیری

یک مورد دسته‌بندی‌شده در یک عملیات events.batch دسته‌ای به دلیل تضاد عملیاتی با سایر موارد دسته‌ای درخواستی قابل اجرا نیست.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conflict",
    "message": "Conflict"
   }
  ],
  "code": 409,
  "message": "Conflict"
 }
}

اقدام پیشنهادی: همه موارد دسته‌بندی‌شده با موفقیت به پایان رسیده و قطعاً ناموفق را حذف کنید و بقیه موارد را در عملیات‌های مختلف events.batch . دسته یا رویداد واحد مربوطه دوباره امتحان کنید.

410: رفت

پارامترهای syncToken یا updatedMin دیگر معتبر نیستند. این خطا همچنین می تواند در صورتی رخ دهد که درخواستی بخواهد رویدادی را که قبلاً حذف شده است حذف کند.

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "fullSyncRequired",
    "message": "Sync token is no longer valid, a full sync is required.",
    "locationType": "parameter",
    "location": "syncToken",
    }
  ],
  "code": 410,
  "message": "Sync token is no longer valid, a full sync is required."
 }
}

یا

{
 "error": {
  "errors": [
   {
    "domain": "calendar",
    "reason": "updatedMinTooLongAgo",
    "message": "The requested minimum modification time lies too far in the past.",
    "locationType": "parameter",
    "location": "updatedMin",
   }
  ],
  "code": 410,
  "message": "The requested minimum modification time lies too far in the past."
 }
}

یا

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "deleted",
    "message": "Resource has been deleted"
   }
  ],
  "code": 410,
  "message": "Resource has been deleted"
 }
}

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

412: پیش شرط ناموفق بود

تگ ارائه شده در هدر If-match دیگر با تگ فعلی منبع مطابقت ندارد.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "conditionNotMet",
    "message": "Precondition Failed",
    "locationType": "header",
    "location": "If-Match",
    }
  ],
  "code": 412,
  "message": "Precondition Failed"
 }
}

اقدام پیشنهادی: موجودیت را دوباره واکشی کنید و تغییرات را دوباره اعمال کنید. برای جزئیات بیشتر به دریافت نسخه های خاص منابع مراجعه کنید.

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

یک خطای rateLimitExceeded زمانی رخ می دهد که کاربر در مدت زمان معین درخواست های زیادی ارسال کرده باشد.

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

اقدام پیشنهادی: خطاهای rateLimitExceeded می‌توانند کدهای خطای 403 یا 429 را برگردانند—در حال حاضر آنها از نظر عملکردی مشابه هستند و باید با استفاده از عقب‌نشینی نمایی به همان روش پاسخ داده شوند. علاوه بر این، مطمئن شوید که برنامه شما از بهترین شیوه های مدیریت سهمیه ها پیروی می کند.

500: خطای Backend

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

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

اقدام پیشنهادی: از عقب نشینی نمایی استفاده کنید.