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

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