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

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