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

عندما يكون طلب البيانات من واجهة برمجة التطبيقات ناجحًا، تعرض واجهة برمجة التطبيقات رمز الحالة 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
رسالة وصف موجز للخطأ
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 تم تجاوز الحصة تم رفض الطلب بسبب بلوغ حدود حصة واجهة برمجة التطبيقات. لمزيد من المعلومات، يُرجى الاطّلاع على الحدود القصوى والحصص في Data API. قد تكون تجاوزت الحدود المسموح بها لكل مشروع أو لكل موقع.
500 INTERNAL خطأ في الخادم الداخلي حدث خطأ غير متوقَّع في الخادم. وهذه عادةً مشكلة مؤقتة. ننصحك بإعادة محاولة إرسال الطلب باستخدام خوارزمية الرقود الأسي الثنائي. لتجنُّب تجاوز الحصص المخصّصة لأخطاء الخادم، من المهم استخدام خوارزمية الرقود الأسي الثنائي مع حدود إعادة المحاولة.
503 UNAVAILABLE الخدمة غير متوفرة الخدمة غير متوفرة مؤقتًا. وهذه عادةً مشكلة مؤقتة. ننصحك بإعادة محاولة إرسال الطلب باستخدام خوارزمية الرقود الأسي الثنائي. لتجنُّب تجاوز الحصص المخصّصة لأخطاء الخادم، من المهم استخدام خوارزمية الرقود الأسي الثنائي مع حدود إعادة المحاولة.