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

تعرض واجهة برمجة التطبيقات 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"
 }
}

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

• تأكَّد من أنّ تطبيقك يتّبع أفضل الممارسات الواردة في إدارة الحصص.
• رفع الحصة لكل مستخدم في مشروع Play 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": "لم يتم العثور على الصفحة" } ], "الرمز": 404, "message": "لم يتم العثور على الصفحة" } }

الإجراء المقترَح: استخدِم ميزة تراجع أسّي.

409: المعرِّف المطلوب موجود سلفًا

تتوفّر نسخة برقم التعريف المحدّد في مساحة التخزين.

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

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

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: فشل الشرط المسبق

علامة etag التي تم توفيرها في العنوان 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"
 }
}

الإجراء المقترَح: استخدِم ميزة تراجع أسّي.