معالجة أخطاء واجهة برمجة التطبيقات

تعرض واجهة برمجة التطبيقات Calendar API مستويَين من معلومات الخطأ:

• رموز خطأ HTTP ورسائله في الرأس
• عنصر JSON في نص الاستجابة يتضمّن تفاصيل إضافية يمكن أن تساعدك في تحديد كيفية التعامل مع الخطأ

تقدّم بقية هذه الصفحة مرجعًا لأخطاء "تقويم Google"، مع بعض الإرشادات حول كيفية التعامل معها في تطبيقك.

ننصح بشدة باختبار معالجة الأخطاء في تطبيقك في بيئة حقيقية.

تنفيذ خوارزمية الرقود الأسي

تقدّم مستندات Cloud APIs شرحًا جيدًا للوقت المتزايد بين عمليات إعادة المحاولة وكيفية استخدامه مع واجهات برمجة التطبيقات في 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: تم تجاوز الحد الأقصى لمعدل إرسال المستخدمين

تمّ الوصول إلى أحد الحدود المسموح بها في "وحدة تحكّم المطوّرين".

{
 "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" التي تم وضعها لحماية مستخدمي Google وبنيتها الأساسية من سلوكيات إساءة الاستخدام.

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

الإجراءات المقترَحة:

• يمكنك الاطّلاع على مزيد من المعلومات حول حدود استخدام "تقويم Google" في مساعدة مشرف Google Workspace.

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": "Not Found" } }

الإجراء المقترَح: استخدِم خوارزمية الرقود الأسي الثنائي.

409: المعرّف المطلوب متوفّر من قبل

هناك مثيل يحمل المعرّف المحدّد في مساحة التخزين.

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

الإجراء المقترَح: أنشئ معرّفًا جديدًا إذا كنت تريد إنشاء مثيل جديد، وإلا استخدِم طلب update.

409: تعارض

لا يمكن تنفيذ عنصر مجمّع داخل عملية events.batch بسبب تعارض في العملية مع عناصر مجمّعة أخرى مطلوبة.

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

الإجراء المقترَح: استبعِد جميع العناصر المجمّعة التي اكتملت بنجاح وجميع العناصر التي تعذّر إكمالها بالتأكيد، وأعِد محاولة تنفيذ العناصر المتبقية في events.batch مختلف أو عمليات حدث فردية مقابلة.

410: Gone

لم تعُد المَعلمتان 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: Precondition Failed

لم يعُد علامة الهامش التي تم توفيرها في عنوان 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: خطأ في الواجهة الخلفية

حدث خطأ غير متوقّع أثناء معالجة الطلب.

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

الإجراء المقترَح: استخدِم خوارزمية الرقود الأسي الثنائي.