حل الأخطاء

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

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

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

ملخّص رموز حالة HTTP

رمز الخطأ	الوصف
`200 - OK`	نجح الطلب (هذه هي الاستجابة العادية لطلبات HTTP الناجحة).
`400 - Bad Request`	لا يمكن تنفيذ الطلب بسبب حدوث خطأ في البرنامج.
`401 - Unauthorized`	يحتوي الطلب على بيانات اعتماد غير صالحة.
`403 - Forbidden`	تم تلقّي الطلب وفهمه، ولكن ليس لدى المستخدم الإذن بتنفيذه.
`404 - Not Found`	تعذّر العثور على الصفحة المطلوبة.
`429 - Too Many Requests`	عدد الطلبات إلى واجهة برمجة التطبيقات كبير جدًا.
`500, 502, 503, 504 - Server Errors`	يحدث خطأ غير متوقّع أثناء معالجة الطلب.

أخطاء 400

تشير هذه الأخطاء إلى أنّ الطلب يتضمّن خطأ، وغالبًا ما يكون ذلك بسبب عدم توفّر معلَمة مطلوبة.

`badRequest`

يمكن أن يحدث هذا الخطأ بسبب أيّ من المشاكل التالية في الرمز:

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

في ما يلي نموذج 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

تعني هذه الأخطاء أنّ الطلب لا يحتوي على رمز دخول صالح.

`authError`

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

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

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

للحصول على معلومات إضافية حول حدود Gmail، يُرجى الاطّلاع على حدود الاستخدام.

أخطاء 403

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على حدود الاستخدام.

`dailyLimitExceeded`

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

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

يظهر هذا الخطأ عندما يضع مالك التطبيق حدًا أقصى للحصة بهدف الحدّ من استخدام مورد معيّن. لإصلاح هذا الخطأ، عليك زيادة الحصة في مشروع Google Cloud. لمزيد من المعلومات، يُرجى الاطّلاع على إدارة حدود الحصة.

`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."
  }
}

لحلّ هذا الخطأ، جرِّب ما يلي:

أبلِغ المستخدم بأنّ النطاق لا يسمح لتطبيقك بالوصول إلى Gmail.
اطلب من المستخدم التواصل مع مشرف النطاق لطلب منح تطبيقك إذن الوصول.

`rateLimitExceeded`

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

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

لحلّ هذا الخطأ، جرِّب ما يلي:

قدِّم طلبًا لزيادة الحصة.
استخدِم الرقود الأسي الثنائي لإعادة محاولة الطلب.

`userRateLimitExceeded`

يحدث هذا الخطأ عند بلوغ الحد الأقصى المسموح به لكل مستخدم. في ما يلي نموذج JSON يمثّل هذا الخطأ:

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

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

أخطاء 429

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

لا يمكن زيادة الحدود لكل مستخدم لأي سبب. لمزيد من المعلومات حول الحدود، يُرجى الاطّلاع على حدود الاستخدام.

حدود إرسال الرسائل

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

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

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

الحدود القصوى المسموح بها لمعدل نقل البيانات

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

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

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

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

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

أخطاء 500 و502 و503 و504

تحدث هذه الأخطاء عندما يظهر خطأ غير متوقّع في الخادم أثناء معالجة الطلب. يمكن أن تتسبّب مشاكل مختلفة في حدوث هذه الأخطاء، بما في ذلك تداخل توقيت الطلب مع طلب آخر أو طلب إجراء غير متاح، مثل محاولة تعديل أذونات صفحة واحدة في "مواقع Google" بدلاً من الموقع الإلكتروني بأكمله.

في ما يلي قائمة بأخطاء 5xx:

‫500 Backend error
‫502 Bad Gateway
‫503 Service Unavailable
‫504: انتهت مهلة البوابة

backendError

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

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

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

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

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

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

إدارة حدود الحصة

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

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

لمزيد من المعلومات، يُرجى الاطّلاع على عرض الحصص وإدارتها.

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

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