حل الأخطاء

تعرض 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."
  }
}

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

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

rateLimitExceeded

يشير هذا الخطأ إلى أنّ المستخدم قد وصل إلى الحد الأقصى لمعدّل الطلبات المسموح به في واجهة برمجة تطبيقات Gmail. يختلف هذا الحدّ حسب نوع الطلب. في ما يلي نموذج 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 "Too many requests: Too many concurrent requests for user" (عدد كبير جدًا من الطلبات: عدد كبير جدًا من الطلبات المتزامنة للمستخدم).

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

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

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

  • ‫500 Backend error
  • ‫502: مدخل غير صالح
  • ‫503 Service unavailable
  • ‫504: انتهت مهلة البوابة

backendError

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

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

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

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

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

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

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

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

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

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

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

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