حل الأخطاء

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

تُفرض هذه الحدود على كل مستخدم، ويتم مشاركتها بين جميع برامج المستخدم، سواء كانت برامج API أو برامج أصلية/ويب أو SMTP MSA. في حال تجاوز هذه الحدود، سيتم عرض الخطأ 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 طلبًا. للحصول على معلومات حول كيفية تجميع الطلبات، راجِع مقالة تجميع الطلبات.