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

رابط برنامه‌نویسی کاربردی تقویم گوگل (Google Calendar API) دو سطح از اطلاعات خطا را برمی‌گرداند:

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

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

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

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

مستندات فضای ابری گوگل ، بک‌آف نمایی و نحوه استفاده از آن با APIهای گوگل را توضیح می‌دهد.

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

این بخش نمایش کامل 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"
  }
}

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

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

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

کاربر به حداکثر نرخ درخواست 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."
  }
}

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

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

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

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

۴۰۴: یافت نشد

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

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

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found"
      }
    ],
    "code": 404,
    "message": "Not Found"
  }
}

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

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

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

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

اقدام پیشنهادی: اگر می‌خواهید یک نمونه جدید ایجاد کنید، یک شناسه جدید ایجاد کنید؛ در غیر این صورت، از متد events.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"
  }
}

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