تعرض واجهة برمجة التطبيقات الخاصة بتقويم Google مستويَين من معلومات الخطأ:
- رموز خطأ HTTP ورسائله في العنوان
- عنصر JSON في نص الردّ يتضمّن تفاصيل إضافية يمكن أن تساعدك في تحديد كيفية التعامل مع الخطأ.
يقدّم الجزء المتبقي من هذه الصفحة مرجعًا لأخطاء "تقويم Google"، مع بعض الإرشادات حول كيفية التعامل معها في تطبيقك.
تنفيذ خوارزمية الرقود الأسي الثنائي
يتضمّن مستند Cloud APIs شرحًا جيدًا عن التراجع الأسي وكيفية استخدامه مع Google APIs.
الأخطاء والإجراءات المقترَحة
يقدّم هذا القسم تمثيل 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" لكل تقويم أو لكل مستخدم تمت مصادقته.
{
"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."
}
}
الإجراءات المقترَحة:
- إذا كنت تستخدم الأحداث: إدراج أو الأحداث: استيراد أو الأحداث: تعديل، ولم يتضمّن طلبك أي سمات مشترَكة، يكون ذلك مكافئًا لمحاولة ضبطها على قيمها التلقائية. ننصحك باستخدام Events: patch بدلاً من ذلك.
- إذا كان طلبك يتضمّن سمات مشتركة، تأكَّد من أنّك تحاول تغيير هذه السمات فقط إذا كنت تعدّل نسخة المنظِّم.
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: Conflict
يتعذّر تنفيذ عنصر مجمّع داخل عملية 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: لم يتم استيفاء الشرط المسبق
لم يعُد etag المقدَّم في العنوان If-match يتطابق مع etag الحالي للمورد.
{
"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"
}
}
الإجراء المقترَح: استخدِم الرقود الأسي الثنائي.