حل الأخطاء

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

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

من المفترض أن ترصد تطبيقات Gmail جميع الأخطاء التي قد تظهر عند استخدام واجهة برمجة تطبيقات REST وتعالجها. يوفر هذا الدليل إرشادات حول كيفية حل أخطاء واجهة برمجة التطبيقات معينة.

حل خطأ 400: الطلب غير صالح

قد ينتج هذا الخطأ عن هذه الأخطاء في التعليمات البرمجية:

• لم يتم تقديم حقل مطلوب أو مَعلمة مطلوبة.
• القيمة المقدّمة أو مجموعة غير صالحة من الحقول المقدّمة.
• مرفق غير صالح.

ملاحظة: هذه القائمة ليست شاملة، وقد تؤدي حالات أخرى إلى حدوث الخطأ 400.

في ما يلي نموذج لتمثيل JSON لهذا الخطأ:

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

لإصلاح هذا الخطأ، تحقَّق من الحقل message واضبط الرمز وفقًا لذلك.

حل خطأ 401: بيانات الاعتماد غير صالحة

يشير خطأ 401 إلى أن رمز الدخول الذي تستخدمه إما منتهي الصلاحية أو غير صالح. يمكن أن يحدث هذا الخطأ أيضًا بسبب عدم توفُّر تفويض للنطاقات المطلوبة. في ما يلي تمثيل JSON لهذا الخطأ:

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

لإصلاح هذا الخطأ، عليك إعادة تحميل رمز الدخول باستخدام الرمز المميّز للتحديث الطويل الأمد. إذا كنت تستخدم مكتبة برامج، ستعالج هذه المكتبة تلقائيًا تحديث الرمز المميّز. إذا تعذّر ذلك، يجب توجيه المستخدم إلى مسار OAuth، كما هو موضح في مصادقة تطبيقك باستخدام Gmail.

لمزيد من المعلومات حول حدود Gmail، يمكنك الرجوع إلى حدود الاستخدام.

حل خطأ 403: تم تجاوز الحد الأقصى للاستخدام

يحدث الخطأ 403 عند تجاوز الحدّ الأقصى للاستخدام أو عدم امتلاك المستخدم للامتيازات الصحيحة. لتحديد نوع الخطأ، يمكنك تقييم الحقل reason لترميز JSON المعروض. يحدث هذا الخطأ في الحالات التالية:

• تم تجاوز الحد اليومي.
• تم تجاوز حد معدل المستخدمين.
• تم تجاوز الحدّ الأقصى لمعدّل المشروع.
• لا يمكن استخدام تطبيقك ضمن نطاق المستخدم الذي تمت مصادقته.

لمزيد من المعلومات حول حدود Gmail، يمكنك الرجوع إلى حدود الاستخدام.

حلّ خطأ 403: تم تجاوز الحد اليومي

يشير خطأ dailyLimitExceeded إلى أنّه تم الوصول إلى الحدّ الأقصى لحدود واجهة برمجة التطبيقات المجّانية لمشروعك. في ما يلي تمثيل JSON لهذا الخطأ:

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

لإصلاح هذا الخطأ:

1. الانتقال إلى وحدة التحكم في واجهة Google API
2. اختَر مشروعك.
3. انقر على علامة التبويب الحصص.
4. طلب حصة إضافية. لمزيد من المعلومات، راجِع طلب حصة إضافية.

لمزيد من المعلومات حول حدود Gmail، يمكنك الرجوع إلى حدود الاستخدام.

حل خطأ 403: تم تجاوز حد معدل المستخدم

يشير خطأ userRateLimitExceeded إلى أنّه تمّ الوصول إلى الحدّ الأقصى المسموح به لكل مستخدم. في ما يلي تمثيل JSON لهذا الخطأ:

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

لإصلاح هذا الخطأ، جرِّب تحسين رمز تطبيقك لتقديم طلبات أقل أو إعادة محاولة إرسال الطلبات. لمزيد من المعلومات حول إعادة محاولة إرسال الطلبات، يمكنك الرجوع إلى إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها لحل الأخطاء.

لمزيد من المعلومات حول حدود Gmail، يمكنك الرجوع إلى حدود الاستخدام.

حل خطأ 403: تم تجاوز الحد الأقصى لمعدّل الزحف

يشير خطأ rateLimitExceeded إلى أنّ المستخدم قد وصل إلى الحدّ الأقصى لمعدّل الطلبات في واجهة برمجة التطبيقات Gmail API. ويختلف هذا الحد حسب نوع الطلبات. في ما يلي تمثيل JSON لهذا الخطأ:

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

لإصلاح هذا الخطأ، يُرجى إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها.

لمزيد من المعلومات حول حدود Gmail، يمكنك الرجوع إلى حدود الاستخدام.

حل خطأ 403: لا يمكن استخدام التطبيق الذي يحمل المُعرّف {appId} داخل نطاق المستخدم الذي تمت مصادقته

يحدث خطأ domainPolicy عندما لا تسمح سياسة نطاق المستخدم بوصول تطبيقك إلى Gmail. في ما يلي تمثيل JSON لهذا الخطأ:

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

لإصلاح هذا الخطأ:

1. يُرجى إبلاغ المستخدم بأنّ النطاق لا يسمح لتطبيقك بالوصول إلى Gmail.
2. توجيه المستخدم للتواصل مع مشرف النطاق لطلب الوصول إلى تطبيقك.

حل خطأ 429: عدد كبير جدًا من الطلبات

يمكن أن يحدث خطأ 429 "عدد كبير جدًا من الطلبات" بسبب الحدود اليومية لكل مستخدم (بما في ذلك حدود إرسال البريد) أو حدود معدل نقل البيانات أو حد الطلبات المتزامنة لكل مستخدم. في ما يلي معلومات حول كل حد. ومع ذلك، يمكن حلّ كل حدّ من القيود إما من خلال محاولة إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها أو تقسيم المعالجة على حسابات متعددة في Gmail. لا يمكن زيادة الحدود المسموح بها لكل مستخدم لأي سبب من الأسباب. لمزيد من المعلومات حول الحدود القصوى المسموح بها للاستخدام، يمكنك الاطّلاع على الحدود القصوى للاستخدام.

حدود إرسال البريد

تفرض واجهة برمجة التطبيقات Gmail API الحدود القصوى اليومية لإرسال الرسائل الإلكترونية. تختلف هذه الحدود بالنسبة إلى مستخدمي Google Workspace خدمة الدفع ومستخدمي الفترة التجريبية gmail.com. للتعرّف على هذه الحدود، يمكنك الاطّلاع على حدود الإرسال على Gmail في Google Workspace.

تتوفر هذه الحدود لكل مستخدم وتتم مشاركتها من قِبل جميع برامج المستخدم، سواء كانت برامج واجهة برمجة التطبيقات أو البرامج الأصلية/الويب أو اتفاقية الخدمة الرئيسية (MSA) عبر SMTP. في حال تجاوز هذه الحدود، يتم عرض خطأ HTTP 429 Too Many Requests "تم تجاوز الحد الأقصى لمعدل المستخدم" "(إرسال البريد)" مع مرور الوقت لإعادة المحاولة. يُرجى العِلم بأنّ تجاوز الحدود اليومية قد يؤدي إلى ظهور هذه الأنواع من الأخطاء لعدة ساعات قبل قبول الطلب.

يُعد مسار إرسال البريد معقدًا: فبمجرد أن يتجاوز المستخدم حصته، قد يكون هناك تأخير لعدة دقائق قبل أن تبدأ واجهة برمجة التطبيقات في عرض 429 ردًا على الخطأ. لذلك لا يمكنك افتراض أن الرد 200 يعني أنه تم إرسال البريد الإلكتروني بنجاح.

حدود معدل نقل البيانات

تتضمن واجهة برمجة التطبيقات حدود معدل نقل البيانات للتحميل والتنزيل لكل مستخدم تساوي بروتوكول IMAP ولكنه مستقل عنه. تتم مشاركة هذه الحدود على مستوى جميع برامج واجهة برمجة التطبيقات Gmail API لمستخدم معيّن.

لا يتمّ فرض هذه الحدود إلّا في الحالات الاستثنائية أو المسيئة. إذا تم تجاوز هذه الحدود، يتم عرض خطأ HTTP 429 Too Many Requests "تم تجاوز الحد الأقصى لمعدل المستخدمين"، مع إضافة وقت لإعادة المحاولة. تجدر الإشارة إلى أنّ تجاوز الحدود اليومية قد يؤدي إلى حدوث هذه الأنواع من الأخطاء لعدة ساعات قبل قبول الطلب.

الطلبات المتزامنة

تفرض واجهة برمجة التطبيقات Gmail API حدًا أقصى للطلبات المتزامنة لكل مستخدم (بالإضافة إلى حد السعر لكل مستخدم). تتم مشاركة هذا الحد من خلال جميع برامج واجهة برمجة التطبيقات Gmail API التي تصل إلى مستخدم معيّن، وتضمن عدم تحميل أي برنامج واجهة برمجة تطبيقات عبئًا زائدًا على صندوق بريد مستخدم Gmail أو خادم الخلفية.

قد يؤدي تقديم العديد من الطلبات المتوازية لمستخدم واحد أو إرسال دفعات تحتوي على عدد كبير من الطلبات إلى ظهور هذا الخطأ. يمكن أيضًا أن يؤدي عدد كبير من برامج واجهة برمجة التطبيقات المستقلة التي تصل إلى صندوق بريد مستخدم Gmail في الوقت نفسه إلى ظهور هذا الخطأ. إذا تم تجاوز هذا الحدّ، يتم عرض الخطأ HTTP 429 Too Many Requests "هناك عدد كبير جدًا من الطلبات المتزامنة للمستخدم".

حل الخطأ 500: خطأ الخلفية

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

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

لإصلاح هذا الخطأ، يُرجى إعادة محاولة إرسال الطلبات التي تعذّر تنفيذها. فيما يلي قائمة بـ 500 خطأ:

• 502 بوابة غير صالحة
• 503 الخدمة غير متوفرة
• انتهت مهلة البوابة 504

إعادة محاولة تنفيذ الطلبات التي تعذّر تنفيذها لحل الأخطاء

يمكنك بشكل دوري إعادة محاولة تنفيذ الطلب الذي تعذّر تحميله على فترات زمنية متزايدة لمعالجة الأخطاء المتعلّقة بالحدود القصوى للمعدّل أو حجم الشبكة أو وقت الاستجابة. على سبيل المثال، يمكنك إعادة محاولة تنفيذ طلب فاشل بعد ثانية واحدة، ثم بعد ثانيتين، ثم بعد أربع ثوانٍ. يُطلَق على هذه الطريقة اسم خوارزمية الرقود الأسي الثنائي ويتم استخدامها لتحسين استخدام معدّل نقل البيانات وزيادة سرعة معالجة الطلبات في البيئات المتزامنة.

بدء فترات إعادة المحاولة بعد ثانية واحدة على الأقل من حدوث الخطأ

عرض حدود الاستخدام أو تغييرها، وزيادة الحصة

لعرض حدود الاستخدام أو تغييرها لمشروعك، أو لطلب زيادة في حصتك، عليك اتّباع الخطوات التالية:

1. إذا لم يكن لديك حساب فوترة لمشروعك من قبل، عليك إنشاء حساب.
2. انتقِل إلى صفحة "واجهات برمجة التطبيقات المفعَّلة" في مكتبة واجهة برمجة التطبيقات في وحدة تحكُّم واجهة برمجة التطبيقات، واختَر واجهة برمجة التطبيقات من القائمة.
3. لعرض الإعدادات المتعلقة بالحصص وتغييرها، اختَر الحصص. لعرض إحصاءات الاستخدام، انقر على الاستخدام.

الطلبات المجمّعة

وننصح باستخدام التجميع، ولكن من المرجّح أن تؤدي أحجام الدُفعات الأكبر إلى فرض قيود على المعدّل. لا يوصى بإرسال دفعات أكبر من 50 طلبًا. للحصول على معلومات حول كيفية تجميع الطلبات، راجِع طلبات التجميع.