حل الأخطاء

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

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

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

حلّ الخطأ 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.
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 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

إعادة محاولة إجراء الطلبات المتعذِّرة لحلّ الأخطاء

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

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

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

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

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

طلبات مجمّعة

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