الردود على الأخطاء

عند نجاح طلب بيانات من واجهة برمجة التطبيقات، تعرض واجهة برمجة التطبيقات رمز الحالة 200 OK مع البيانات المطلوبة في نص الاستجابة. في حال حدوث خطأ، تعرض واجهة برمجة التطبيقات أحد رموز الخطأ الأساسية التي تحدّدها Google APIs، والتي يتم ربطها برمز حالة HTTP، ونص استجابة يحتوي على معلومات الخطأ. عند مواجهة خطأ، يمكنك الاطّلاع على الحقلَين message وstatus في نص استجابة JSON للحصول على تفاصيل محدّدة تساعد في تحديد المشاكل وحلّها.

تنسيق الخطأ

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

{
  "error": {
    "code": 403,
    "message": "User does not have sufficient permissions for this property.",
    "status": "PERMISSION_DENIED"
  }
}

يحتوي الكائن error على الحقول التالية:

الحقل الوصف
code رمز حالة HTTP، مثل 400 أو 401 أو 403 أو 429 أو 500
message وصف قصير للخطأ
status رمز الخطأ الأساسي، مثل INVALID_ARGUMENT أو UNAUTHENTICATED أو PERMISSION_DENIED أو RESOURCE_EXHAUSTED أو INTERNAL

الأخطاء الشائعة

يسرد الجدول التالي الأخطاء الشائعة التي تعرضها واجهة برمجة التطبيقات.

رمز حالة HTTP الرمز الأساسي السبب الوصف
400 INVALID_ARGUMENT طلب سيئ الطلب غير صالح. يمكن أن يكون السبب في ذلك معلّمات غير صالحة أو غير متوفّرة، مثل نطاق تاريخ غير صحيح أو فلتر غير صالح.
401 UNAUTHENTICATED بيانات الاعتماد غير صالحة. لا يحتوي الطلب على بيانات اعتماد مصادقة صالحة للمورد المستهدَف. يمكن أن يحدث ذلك إذا كان رمز الدخول عبر OAuth 2.0 غير متوفّر أو غير صالح أو منتهي الصلاحية. اتّبِع التعليمات الواردة في المصادقة باستخدام OAuth 2.0 للحصول على رمز صالح.
403 PERMISSION_DENIED الأذونات غير كافية لا يملك المستخدم الذي تمت المصادقة عليه إذن الوصول إلى موقع على "إحصاءات Google" المطلوب.
429 RESOURCE_EXHAUSTED تم تجاوز الحصة تم رفض الطلب بسبب الوصول إلى الحدود القصوى لحصة واجهة برمجة التطبيقات. اطّلِع على حدود واجهة برمجة التطبيقات للبيانات وحصصها لمزيد من المعلومات. قد تكون تتجاوز الحدود القصوى لكل مشروع أو لكل موقع.
500 INTERNAL خطأ في الخادم الداخلي حدث خطأ غير متوقَّع في الخادم. عادةً ما تكون هذه المشكلة مؤقتة. ننصح بإعادة محاولة إرسال الطلب باستخدام خوارزمية الرقود الأسي الثنائي . لتجنُّب تجاوز الحصص المخصّصة لأخطاء الخادم، من المهم استخدام خوارزمية الرقود الأسي الثنائي مع حدود إعادة المحاولة.
503 UNAVAILABLE الخدمة غير متوفرة الخدمة غير متوفرة مؤقتًا. عادةً ما تكون هذه المشكلة مؤقتة. ننصح بإعادة محاولة إرسال الطلب باستخدام خوارزمية الرقود الأسي الثنائي . لتجنُّب تجاوز الحصص المخصّصة لأخطاء الخادم، من المهم استخدام خوارزمية الرقود الأسي الثنائي مع حدود إعادة المحاولة.