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

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

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

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

پیاده سازی پسروی نمایی

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

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

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

۴۰۰: درخواست اشتباه

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

{
 "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."
 }
}

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

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

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

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

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

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

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

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

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

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

۴۰۳: از حد مجاز نرخ تجاوز شده است

کاربر به حداکثر نرخ درخواست API تقویم گوگل به ازای هر تقویم یا به ازای هر کاربر احراز هویت شده رسیده است.

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

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

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

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

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

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

۴۰۳: برای افراد غیر سازمان‌دهنده ممنوع است

درخواست به‌روزرسانی رویداد تلاش می‌کند یکی از ویژگی‌های رویداد مشترک را در کپی‌ای که متعلق به برگزارکننده نیست، تنظیم کند. ویژگی‌های مشترک (برای مثال، 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."
 }
}

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

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

۴۰۴: یافت نشد

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

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

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

    { "خطا": { "خطاها": [ { "دامنه": "جهانی", "دلیل": "یافت نشد", "پیام": "یافت نشد" } ], "کد": 404, "پیام": "یافت نشد" } }

اقدام پیشنهادی: از روش پس‌روی نمایی استفاده کنید.

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

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

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

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

۴۰۹: درگیری

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

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

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

۴۱۰: رفته

پارامترهای 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 ، اطلاعات ذخیره شده را پاک کرده و دوباره همگام‌سازی کنید. برای جزئیات بیشتر به بخش «همگام‌سازی کارآمد منابع» مراجعه کنید. برای رویدادهایی که قبلاً حذف شده‌اند، اقدام دیگری لازم نیست.

۴۱۲: پیش‌شرط ناموفق بود

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

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

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

۴۲۹: درخواست‌های بسیار زیاد

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

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

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

۵۰۰: خطای بخش مدیریت

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

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

اقدام پیشنهادی: از روش پس‌روی نمایی استفاده کنید.